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

package/.claude/skills/create-project/provision.mjs

@@ -315,9 +315,22 @@ function printSummary() {
 		// Defensive: the API's `added`/`skipped` entries may be objects, strings, or
 		// null. Never let summary formatting throw — it would swallow real warnings.
 		const fmt = (g) => (g == null ? null : typeof g === 'string' ? g : (g.property_name || g.name || null));
-		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
+		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean);
+		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean);
+		// `added`/`skipped` are not always populated (a create that lands via a
+		// different code path can return both empty), which made a perfectly good
+		// provision print "added [(none)] skipped [(none)]" and read as a failure.
+		// `all_group_keys` is the authoritative post-state, so report against that
+		// and only fall back to the deltas when it's absent.
+		const all = (groupKeyResult?.all_group_keys || []).map(fmt).filter(Boolean);
+		if (all.length) {
+			const present = groupKeys.map((g) => g.property_name).filter((p) => all.includes(p));
+			const missing = groupKeys.map((g) => g.property_name).filter((p) => !all.includes(p));
+			console.log(`group keys:     in project [${present.join(', ') || '(none)'}]${missing.length ? `  MISSING [${missing.join(', ')}]` : ''}`);
+			if (missing.length) warnings.push(`group keys missing after addGroupKey: ${missing.join(', ')}`);
+		} else {
+			console.log(`group keys:     added [${added.join(', ') || '(none)'}]  skipped [${skipped.join(', ') || '(none)'}]`);
+		}
 	}
 	console.log(`business ctx:   ${content.length} chars uploaded (source: ${ctxSource})`);
 	console.log(`credentials:    ${wroteBack ? 'written back into dungeon ✓' : 'NOT written (see warnings)'}`);

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

@@ -0,0 +1,254 @@
+---
+name: headless-build
+description: Use after a dungeon's data is loaded into a real Mixpanel project — builds the full demoable environment with mixpanel-headless (dashboards, charts, Lexicon, cohorts, custom properties, behaviors/metrics/formulas, annotations) targeted at that dungeon's engineered stories, then verifies the stories still read live. Final step after create-dungeon / write-hooks / verify-dungeon / create-project.
+argument-hint: [dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]
+model: claude-opus-4-6
+effort: max
+---
+
+# Headless Build — turn a loaded project into a demo
+
+Last step of the pipeline:
+
+```
+/create-dungeon → /write-hooks → /verify-dungeon → /create-project → /headless-build
+```
+
+The project already has data. This skill builds everything a human sees: themed
+dashboards whose narrative is computed from the live data, an annotated Lexicon,
+saved cohorts and custom properties, saved behaviors/metrics/formulas, and
+annotations that explain the engineered moments. Then it re-measures the hook
+stories **against the live project** and fails if they no longer read.
+
+That last step is the point. Local story verification passes on the generated
+array in memory; it never sees what survived ingest. A build can render five
+perfect dashboards on top of a story that silently collapsed on the way in.
+
+## Scope
+
+In scope: dashboards + charts, Lexicon enrichment, cohorts, custom properties,
+behaviors/metrics/formulas, annotations, and live story verification.
+
+Out of scope: changing the dungeon, regenerating or re-sending data. If the data
+is wrong, fix the dungeon and re-run `/create-project` — do not paper over it
+with dashboard copy.
+
+## Prerequisites
+
+- The dungeon's `creds.json` / `credentials` block exists (`/create-project` ran).
+- Data is actually loaded — `00_auth_check.py` fails loudly if not.
+- `uv` available. `mixpanel_headless` is on PyPI, so it needs no local checkout:
+  `uv run --with mixpanel_headless python <script>`.
+
+## Step 0 — ask who creates the entities
+
+**Ask the user before building.** The answer changes who owns every asset:
+
+| Mode | Effect |
+|---|---|
+| **bearer** (recommended) | Entities are created by a real user via OAuth token (`BEARER_TOKEN` in the repo `.env`). They appear in that person's Mixpanel UI with owner access. |
+| **service** | Entities are created by the dungeon's service account. A human then sees **"Your access: None"**, and custom properties have no share endpoint — so it cannot be fixed from the UI at all. Only correct when no OAuth token exists. |
+
+Default to **bearer** whenever a token is available. To use it with
+`mixpanel_headless`, set `MP_OAUTH_TOKEN` and **unset `MP_USERNAME` / `MP_SECRET`** —
+the SDK prefers the service account whenever the full SA env set is present.
+Power-tools calls must use the same principal (`Authorization: Bearer …`), or
+entities created through that path land back under the service account.
+
+## Reference implementation
+
+`dungeons/user/nyc-dcp/build/` is the worked example — read it before writing a
+new one. (It is gitignored with the rest of `dungeons/user/`, so it lives only in
+the working copy.) Peloton's equivalent is
+`/Users/ak/code/mixpanel-headless/ak/customer_peloton/`.
+
+## Layout
+
+Create the build inside the dungeon's own folder:
+
+```
+dungeons/user/<name>/build/
+├── .env                    # MP_USERNAME / MP_SECRET / MP_PROJECT_ID / MP_REGION
+├── _common.py              # window detection, ws factory + retry, helpers, knobs, cohorts
+├── build_all.py            # one-shot orchestrator, --only / --internal / --from-date
+├── scripts/
+│   ├── 00_auth_check.py         # also prints WHO is authenticated
+│   ├── 01_reset_entities.py     # opt-in: delete this build's own entities
+│   ├── 02_custom_props.py
+│   ├── 03_cohorts.py
+│   ├── 04_lexicon.py
+│   ├── 05_dash_start_here.py    # built LAST — links the other boards by id
+│   ├── 06..09_dash_<story>.py   # one board per engineered story
+│   ├── 10_annotations.py
+│   ├── 11_behaviors_metrics.py  # via power-tools; headless lacks these
+│   └── 99_verify.py
+└── results/                # entities.json registry, window.json, verification_*.json
+```
+
+## Steps
+
+### 1. Read the dungeon
+
+Pull out, from the dungeon file itself: the `stories` export, the HOOK STORIES
+doc block, the knob constants, the event/property schema, and the VALUE MOMENT.
+**Mirror the knob constants into `_common.py`** so dashboard copy quotes the
+designed value while the charts show the measured one. Never let narrative text
+hardcode a number no longer tied to a knob.
+
+### 2. Probe the project before designing
+
+Capabilities differ per project. Run a throwaway probe and design around what
+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**.
+- 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.
+
+### 3. Auto-detect the data window
+
+Never hardcode dates. A regenerated dungeon lands on new ones and every chart
+silently clips. Probe wide at `unit="month"`, then resolve exact days inside the
+non-empty months (day charts cap at 366 days). Cache to `results/window.json`.
+
+### 4. Build entities, then boards
+
+Order matters: custom properties and cohorts first (boards break down by them),
+Lexicon, behaviors/metrics/formulas, annotations, then dashboards, with the
+"Start Here" board last so it can link the others by id.
+
+Keep a `results/entities.json` registry of every created id — the Start Here
+board and the verifier both read it.
+
+### 5. Write boards that argue, not just render
+
+The difference between a dashboard and a demo:
+
+- **Query first, then narrate.** Compute the numbers live, then interpolate them
+  into text cards. Never write a number by hand.
+- **One board per story**, plus a Start Here tour board.
+- **Normalize rates.** Raw totals carry population and activity; the claim is
+  almost always about intensity. Say which denominator you used and why.
+- **Name the confound.** If a chart could be read two ways, put the alternative
+  in the text card and say what rules it out.
+- **End each board with a "So what"** — the decision the board supports.
+- Text card HTML must be single-line (`" ".join(html.split())`) — TipTap mangles
+  newlines.
+
+**Board titles carry no app prefix.** The project is already the app; a
+`"<App> — "` prefix on every board is noise that eats the readable part of the
+name in the sidebar. Title them `Borough Equity & Access`, not
+`NYC DCP — Borough Equity & Access`.
+
+**Always label the legend.** By default a series reads
+`Data Export [Total Events]` — it names the event and the math, not the thing
+being measured. Mixpanel exposes this as **Rename** on a query block; on the
+wire it is `params.sections.show[i].name` plus `userNamed: true` (the flag is
+what stops the UI regenerating the label). Every insights report should pass a
+plain-English label: `Users`, `Exports`, `Comments Filed`.
+
+**Merge KPI cards into ONE multi-metric report.** Four big-number cards do not
+need four saved reports. Each report is another entity to create and another
+query to run, and the rate limit is the binding constraint on a full build.
+Concatenate the `sections.show` arrays of several single-metric queries into one
+params dict and keep `chart_type="insights-metric"` — Mixpanel still renders big
+numbers, one per metric. Only safe when the inputs share a time range and
+report-level filter, since `sections.filter` applies to the whole report; per-metric
+filters have to move into `show[i].behavior.filters`.
+
+**Share everything, and warm the cohorts.** Two separate failure modes:
+
+- *Unshared* — an entity is visible only to its creator. Call
+  `/crud/shareDash` (`view_only: false`) and `/crud/shareCohort`
+  (`can_edit: true`) for everything you create. There is no share endpoint for
+  custom properties, behaviors, or metrics — which is exactly why bearer auth
+  matters: get the owner right at creation, because you cannot fix it after.
+- *Unwarmed* — cohort membership computes **lazily**. A freshly created cohort
+  reports `count: 0` until something queries it, and a cohort showing 0 members
+  reads as broken in a demo. Run one cheap query per cohort after creating it.
+  Verify counts, not just existence.
+
+### 6. Verify against the live project
+
+`99_verify.py` does two checks:
+
+- **structure** — every registered entity still exists.
+- **stories** — re-measure each hook effect live and compare to the knob.
+
+Report MATCH / DIRECTIONAL / MISS per story and exit non-zero on any MISS.
+Use a wider tolerance than the dungeon's own ±10% bar (~25%): Mixpanel's cohort
+membership is computed over the whole window, not the dungeon's internal binning,
+so depth-band style cohorts will not line up exactly.
+
+### 7. Report
+
+Give the user the board URLs
+(`https://mixpanel.com/project/<pid>/view/<wsid>/app/boards/<id>`), the entity
+counts, and the story verdict table.
+
+## Gotchas that cost real time
+
+**Saved cohort ids, never inline definitions.** `Filter.in_cohort(CohortDefinition(...))`
+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>")`.
+
+**`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;
+profile-property and behavior-nested property filters no).
+
+**Rate limits will kill a full build midway.** A build fires several hundred
+queries; the cap trips after the first couple of boards and the rest fail,
+leaving a half-built project that still looks fine until you count the boards.
+The client must therefore:
+
+- **Issue one request at a time**, with a small fixed gap. Parallelism does not
+  help and actively hurts — the cap is request-rate based, so concurrency only
+  reaches the limit sooner and then every worker sits in backoff together.
+- **Back off hard and genuinely exponentially** on 429: start ~30s, double, cap
+  ~15 minutes, ~7 attempts. The cap is per-hour, so short retries just burn
+  attempts without letting the window refill. Retry transient 502s the same way.
+- **Be resumable.** Keep the entity registry on disk and reuse by name, so a
+  killed build picks up where it stopped instead of duplicating.
+
+On Mixpanel-internal projects `--internal` additionally sends the rate-limit
+bypass headers. It is a no-op elsewhere and does *not* remove the need for
+backoff — it supplements it.
+
+**Fewer entities is a rate-limit strategy, not just tidiness.** Merging four KPI
+cards into one multi-metric report removes three creates and three queries from
+every build. Prefer one report with N metrics wherever the chart allows it.
+
+**`ws._api_client` is lazy** — None immediately after construction. Force it via
+`ws._get_api_client()` before patching request headers.
+
+**Idempotency.** Dashboards: delete-by-title then recreate. Everything else:
+look up by name and reuse. Re-running must never duplicate.
+
+## Commands
+
+```bash
+cd dungeons/user/<name>/build
+set -a && . ./.env && set +a
+
+uv run --with mixpanel_headless python build_all.py --auth bearer        # recommended
+uv run --with mixpanel_headless python build_all.py --auth service       # SA-owned assets
+uv run --with mixpanel_headless python build_all.py --internal           # + rate-limit bypass
+uv run --with mixpanel_headless python build_all.py --only reset --apply # wipe this build's entities
+uv run --with mixpanel_headless python build_all.py --only dashboards verify
+uv run --with mixpanel_headless python build_all.py --skip-lexicon
+uv run --with mixpanel_headless python build_all.py --from-date 2026-04-18 --to-date 2026-08-17
+uv run --with mixpanel_headless python scripts/99_verify.py              # verify only
+```
+
+Phases: `auth`, `reset` (opt-in only), `customprops`, `cohorts`, `lexicon`,
+`entities`, `annotations`, `dashboards`, `verify`.
+
+`reset` is never part of the default order — it deletes entities, and only ever
+the ones this build created, matched by name. Use it when assets were created
+under the wrong principal and must be recreated (there is no way to re-own an
+existing custom property).

package/.claude/skills/powertools/SKILL.md

@@ -45,7 +45,27 @@ node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token
 
 GET the path for full docs. Full list: GET `/` and GET `/macro`.
 
-**crud** — `/crud/createProject`, `/crud/deleteProject`, `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/addGroupKey`, `/crud/setBusinessContext` (all used by the create-project skill's `provision.mjs`).
+**crud** — 187 endpoints. GET `/crud` for the full list.
+
+*Project lifecycle* (used by create-project's `provision.mjs`): `/crud/createProject`, `/crud/deleteProject` (**irreversible** — deletes the project and all its data; needs `org_id`), `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/deleteServiceAccount`, `/crud/addGroupKey`, `/crud/deleteGroupKey`, `/crud/setBusinessContext`.
+
+*Analysis entities* (used by the `headless-build` skill for what `mixpanel_headless` does not expose): `/crud/createCohort` + `getCohorts`/`getCohort`/`updateCohort`/`deleteCohort`, `/crud/createBehavior` + `getBehaviors`/`deleteBehavior`, `/crud/createMetric` + `getMetrics`/`deleteMetric`, `/crud/createFormula` + `getFormulas`/`deleteFormula`, `/crud/createDash`/`updateDash`/`pinDash`/`duplicateDash`, `/crud/makeInsightsReport`/`makeFunnelsReport`/`makeFlowsReport`/`makeRetentionReport`, `/crud/createCustomProp`, `/crud/createCustomEvent`, `/crud/createAnnotation`, `/crud/createLookupTable`.
+
+### Entity-CRUD response shapes (verified 2026-08-17 — these bite)
+
+Three different shapes across one API family. Assuming a flat list or a flat `results.id` silently yields `None`/empty rather than erroring:
+
+- **create** returns `{"status":"ok","results":{"<id>":{...}}}` — `results` is keyed BY id, so `results["id"]` is None. Take `next(iter(results.values()))["id"]`.
+- **list** (`getBehaviors`/`getMetrics`/`getFormulas`) returns numerically-keyed entries at the **top level** — `{"0":{...},"1":{...},"duration_ms":…}` — with nothing under `results`. Iterate `raw.values()` and keep dicts that carry a `name`+`id`.
+- `getMetrics` and `getFormulas` return the **same combined set** (metrics and formulas share one store), so dedupe by name if you call both.
+
+### Cohort payload limits (verified on project 4054934)
+
+`/crud/createCohort` accepts the native UI shape: `groups[]` of `cohort_group` (each `{type, event:{resourceType:"cohort",value:"$all_users"}, filters[]}`) plus `determiner: "all"|"any"`. What works and what does not:
+
+- ✅ behavioral counts — `customProperty.behavior` + `filterOperator: "is at least"|"is at most"`; multiple filters in one group give a RANGE; multiple groups give AND (`all`) / OR (`any`).
+- ❌ profile-property filters, and property filters nested inside a `behavior` — both fail with `Failed to resolve cohort references`. Express those as report `where` filters instead.
+- New cohorts report `count: 0` at creation; membership computes asynchronously.
 
 **query** — `/query/getTopEvents` (per-event counts, limit≤100 default), `/query/getEventNames`, `/query/getPropertyValues`, `/query/getTopProperties`, `/query/getSegmentation`, `/query/getFunnel`, `/query/listFunnels`, `/query/listCohorts`, `/query/runJQL`. Rate limits: 5 concurrent / 60 per hour; 1h response cache.
 

package/CHANGELOG.md

@@ -2,6 +2,158 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.6.3 — 2026-08-17
+
+### Fixed
+
+- **Cloned events no longer get deduplicated away by Mixpanel on ingest.** All
+  eight clone-producing helpers now give each clone a fresh `insert_id`:
+  `cloneEvent`, `scaleEventCount`, `injectAfterEvent`, `injectBetween`,
+  `injectBurst`, `injectOnNewDays`, `applyLifecycleWave`, and `applyPathBias`.
+  Four of them (`cloneEvent` and the three `injectAfterEvent`/`injectBetween`/
+  `injectBurst`) copied the template's id verbatim, so clones arrived as
+  byte-identical twins and Mixpanel deduped them server-side. The others deleted
+  the id, which is no safer: `mixpanel-import` runs with `fixData: true` and
+  synthesizes a missing id by content-hashing the record, so identical clones
+  collide into one anyway. Measured on an 8K-user dungeon: 608,081 events
+  generated, 598,555 landed. The loss fell entirely on the two events the hooks
+  clone, and an engineered 4x comment surge read as **1.17x** in the project while
+  local story verification still reported 4.14x — verification never inspects
+  `insert_id`. After the fix, all 608,081 ids are distinct and in-project counts
+  match sent counts exactly. Affects any dungeon whose hooks clone or inject
+  events. New shared helpers `stampFreshInsertId` / `cloneWithFreshId` in
+  `lib/hook-helpers/_internal.js`; every clone site honors an explicit
+  `insert_id` override uniformly. Swept by `tests/unit/clone-insert-id.test.js`,
+  which covers every clone site rather than the one that happened to break.
+- **The engine now guarantees unique `insert_id` across each user's final event
+  stream.** Fixing the clone helpers was not sufficient: hooks are documented to
+  inject events by spreading an existing one, and a spread copies `insert_id`
+  too — so any hand-rolled clone reintroduced the bug. Several shipped dungeons
+  (including `dungeons/technical/simple.js` and most of `dungeons/vertical/`) do
+  exactly that, and measured 160 duplicate ids in a 3,254-event sample. The user
+  loop now re-stamps any duplicate or missing `insert_id` after the `everything`
+  hook, alongside the existing auto-sort and future-time guards. A legitimate
+  stream never carries two events with the same id, so any collision at that
+  point is a clone. Pinned by `tests/integration/insert-id-uniqueness.test.js`.
+  CLAUDE.md's hook rule now points at `cloneEvent` while documenting that a bare
+  spread remains safe.
+- **`mixpanel-import` 3.5.1 → 3.6.1**, which fixes an undercount in the reported
+  user-profile success total (3.5.1 reported 196 profiles sent for a batch of
+  6,049 that had in fact all landed).
+- **`create-project` no longer reports a successful group-key add as a failure.**
+  The summary read `added [(none)] skipped [(none)]` even when the key was created
+  and ready, because the response's `added`/`skipped` arrays are not always
+  populated. It now reports against `all_group_keys`, the authoritative post-state,
+  and warns when a declared key is genuinely absent.
+
+### Added
+
+- **`/headless-build` skill** — final step of the pipeline (after `/create-project`).
+  Builds a demoable Mixpanel environment with `mixpanel_headless`: dashboards whose
+  narrative text is computed live from the project, Lexicon enrichment, saved
+  cohorts, custom properties, behaviors/metrics/formulas, and annotations — then
+  re-measures every hook story against the live project and fails on a miss.
+- **`powertools` skill: entity-CRUD index.** Documents the three inconsistent
+  response shapes across the create/list endpoints, the `createCohort` payload
+  contract, and which cohort filter types the API accepts.
+
+## 1.6.2 — 2026-07-30
+
+### Fixed
+
+- **Running the same dungeon twice in one process no longer collapses the second
+  run.** `validateDungeonConfig` enriched in place — stamping `isStrictEvent` on
+  funnel-step events and `conversionWindowDays` / `_experiment` on funnels — and
+  `DUNGEON_MASTER` handed the pipeline a shallow spread, so those stamps landed on
+  the caller's own `events` / `funnels` arrays. For a file input that array belongs
+  to the ESM module cache, so run 2 got a config already enriched by run 1: every
+  event pre-promoted to strict, the catch-all funnel swept nothing, and event volume
+  collapsed (measured 317 → 0 on `dungeons/technical/simple.js`). The validator now
+  clones its input and enriches only what it returns; functions (`hook`,
+  `onProgress`, chance-bound prop thunks) are preserved by reference. Affects an
+  object config passed by a caller who reuses it, a file path run more than once in
+  a process, and an array of paths. Not affected: raw-text input (each call writes a
+  fresh temp module) and `scripts/run-many.mjs` (forks a child per dungeon). Pinned
+  by `tests/integration/config-isolation.test.js`.
+- **`verifyDungeon` now applies funnel config to path and JSON inputs.** It read
+  `conversionWindowDays` / `order` back off the caller's own `config`, which for a
+  string input has no `.funnels` at all — so every funnel check silently ran with
+  the default order and an unbounded window. It now reads
+  `result.validatedConfig.funnels`.
+- **`verifyDungeon`'s schema report is no longer spurious.** `validateSchema` also
+  ran against the raw input: a path input has no fields to derive an expected
+  schema from, and a v1.5.1 dungeon keeps `hasAndroidDevices` / `hasBrowser` under
+  `switches`, which `deriveExpectedSchema` only sees once flattened. Both produced
+  a wall of phantom `flagStamping` findings and a permanently false `report.pass`
+  (16 phantom findings on `dungeons/technical/experiments.js`; now 0). It now
+  validates against the config the run actually used.
+- **The 22 shipped `dungeons/vertical/*/*.verify.mjs` wrappers now thread VALIDATED
+  funnels** into `evaluateStories`. They passed `config.funnels` raw, so no funnel
+  story in any vertical had a conversion window — every vertical funnel resolves to
+  a 30- or 45-day `conversionWindowDays` that was being dropped. Pre-existing (these
+  scripts read shards off disk, so nothing ever enriched their config).
+  `validateDungeonConfig` is now exported from `@ak--47/dungeon-master/verify` for
+  exactly this.
+- **`verifyDungeon` throws on a multi-dungeon input** instead of silently verifying
+  `result[0]` and discarding the rest — which returned a green report for dungeons
+  nobody looked at. Call it once per dungeon.
+- **`tests/unit/dungeon-shapes.test.js` no longer asserts the lowercase-hyphen naming
+  convention against `dungeons/user/`.** That directory is gitignored per-machine
+  scratch space, so the check failed on whatever a given developer had checked out
+  locally and was unreproducible in CI. The convention still applies to the tracked
+  `technical/` and `vertical/` dungeons.
+
+### Added
+
+- **`result.validatedConfig`** — the enriched config the run actually used. Read
+  resolved values (`funnels[].conversionWindowDays`, `events[].isStrictEvent`, the
+  resolved dataset window) here now that the validator no longer writes them back to
+  the object you passed in. Two caveats, both documented on the type: credentials
+  are stripped (a Result gets logged), and it is **read-only** — validation is not
+  idempotent, so feeding it back into `DUNGEON_MASTER` grows the funnel set and
+  eventually yields an empty `sequence`. Re-run the original config instead.
+- **`verifyDungeon(config, checks, overrides)`** — an optional third argument,
+  merged into the dungeon before it runs exactly like `DUNGEON_MASTER`'s second
+  argument. Lets CI verify a production-scale dungeon at a small `numUsers` /
+  `numEvents` without editing it. The report also carries `validatedConfig`.
+- **`validateDungeonConfig`** re-exported from `@ak--47/dungeon-master/verify`, so a
+  standalone verify script that reads shards off disk can resolve funnel defaults
+  before calling `evaluateStories` / `applyFunnelDefaults`.
+- **`releaseConnections()`** exported from `lib/orchestrators/mixpanel-sender.js`,
+  for hosts that drive `mixpanel-import` directly and want the same pool teardown.
+
+### Changed
+
+- **`validateDungeonConfig` no longer mutates its input.** Enrichment lands only on
+  the returned object. If you called it directly and then read `isStrictEvent` /
+  `conversionWindowDays` back off the config you passed in, read the return value
+  instead (or `result.validatedConfig` after a run). Running a dungeon is
+  unaffected. This is the fix for the collapse bug above, so it ships on a patch.
+- **`mixpanel-import` bumped `^3.3.2` → `^3.5.1`.** Notable for dungeon-master:
+  - **Flat events past `epochEnd` no longer kill the entire import job.** The sender
+    sets `epochEnd: dayjs().unix()` and dungeon-master events are flat, which on
+    3.3.2 threw `Record has no properties object, cannot fix time` and failed the
+    whole batch; 3.5.1 counts the record as `outOfBounds` and carries on. Verified
+    directly against both versions.
+  - **India-region SCD imports go to `api-in`.** 3.3.2 routed `region: 'IN'` SCD
+    batches to `api-eu`.
+  - **The library no longer installs five process-global handlers**
+    (`unhandledRejection`, `uncaughtException`, `exit`, `SIGINT`, `SIGTERM`) as an
+    import side effect. **Hosts embedding dungeon-master will now crash on uncaught
+    exceptions and unhandled rejections instead of logging and continuing** — those
+    errors were always happening, only the reporting changes. Register your own
+    handlers to restore the old behavior. Upside: `user-loop`'s own SIGINT handler is
+    no longer preempted, so Ctrl+C cancellation works as designed.
+  - Prod-only `npm audit` for the dependency tree: 45 findings → 20 (critical 3 → 1).
+- **`sendToMixpanel` releases mixpanel-import's shared undici connection pools**
+  when it settles, so a host that runs occasional imports doesn't hold ingest
+  sockets open in between. Runs in a `finally`, guarded, and non-fatal; pools are
+  recreated on demand. The pools are process-global, so teardown is refcounted —
+  concurrent `DUNGEON_MASTER()` calls in one process won't close sockets out from
+  under each other.
+- **`engines.node` raised `>=18.0.0` → `>=20.20.0`**, matching what mixpanel-import
+  requires. The old floor had been wrong since 3.3.2 (which already wanted 20.18.1).
+
 ## 1.6.1 — 2026-07-08
 
 ### Fixed

package/dungeons/vertical/ai-platform/ai-platform.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './ai-platform.js';
 
 const PREFIX = process.argv[2] || 'verify-ai-platform';
@@ -51,12 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — the H9 story carries its own explicit
-// 336-hour conversion window (2x the generative window, covering the
-// stretched support), so no funnel-default threading is needed
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/community/community.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './community.js';
 
 const PREFIX = process.argv[2] || 'verify-community';
@@ -51,13 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — the H8/H9 emulator stories carry their
-// own explicit conversion window (48h Content Creation generative window ×
-// the 1.25 free-tier stretch = 60h, covering the stretched support), so no
-// funnel-default threading is needed
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/crypto/crypto.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './crypto.js';
 
 const PREFIX = process.argv[2] || 'verify-crypto';
@@ -63,7 +63,9 @@ const runSql = async (sql) => {
 // assemble chains across unscaled clones and collapse the read.
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/dating/dating.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './dating.js';
 
 const PREFIX = process.argv[2] || 'verify-dating';
@@ -51,13 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — the H9 stories carry their own explicit
-// conversion window (24h Match Flow generative window × the 1.4 max stretch
-// factor = 33.6h, covering the stretched support), so no funnel-default
-// threading is needed
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/devtools/devtools.verify.mjs

@@ -18,7 +18,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './devtools.js';
 
 const PREFIX = process.argv[2] || 'verify-devtools';
@@ -58,7 +58,9 @@ const runSql = async (sql) => {
 // semantics, not cross-event SQL (greedy MIN→MIN picks flatten it).
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/ecommerce/ecommerce.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './ecommerce.js';
 
 const PREFIX = process.argv[2] || 'verify-ecommerce';
@@ -51,11 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — the H8 story carries its own explicit
-// 75-minute pairing window in SQL, so no funnel-default threading is needed
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });

package/dungeons/vertical/education/education.verify.mjs

@@ -17,7 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import { buildIdentityMap, evaluateStories, validateDungeonConfig, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
 import config, { stories } from './education.js';
 
 const PREFIX = process.argv[2] || 'verify-education';
@@ -51,16 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — the emulator stories carry their own
-// explicit conversion windows (H7/H9: 86.4h = 48h generative × the 1.8 free
-// TTC stretch, on the 2-step enrolled→cert read; the 4-step doc funnel would
-// break because H9's annual ×0.5 compression can move a cert before the
-// interior quiz step). H10 pairs in SQL anchored at funnel ENTRY (first
-// 'discussion posted' at/after $experiment_started, conversion within 12h of
-// entry) because the exp→entry lag is arm-dependent.
 const results = await evaluateStories(stories, events, {
 	profiles,
-	funnels: config.funnels,
+	// funnel defaults (conversionWindowDays, order) resolve on the VALIDATED
+	// config — the dungeon was not run in this process, so validate here.
+	funnels: validateDungeonConfig({ ...config, token: '' }).funnels,
 	identityMap: buildIdentityMap(profiles),
 	runSql,
 });