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

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

@@ -0,0 +1,75 @@
+---
+name: powertools
+description: Use when any task needs the Mixpanel Power Tools API ("use powertools") — schema export (get-schema), event volumes, project CRUD, query methods, macros, or snapshotting a prod project's schema to copy it into a dungeon. Companion to create-project (which handles provisioning specifically).
+argument-hint: [what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]
+---
+
+# Power Tools API
+
+Base URL: `https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app`
+
+## Auth model — read this first
+
+- **GET any endpoint path = documentation, no auth.** Always `curl -s GET <base><path>` before first use of an unfamiliar endpoint — docs include exact body params and response shapes.
+- **POST = execute.** `Authorization: Bearer <oauth-token>` (employee OAuth from repo `.env` `BEARER_TOKEN`, or a customer's OAuth token) or `Basic base64(service_acct:secret)`.
+- **Customer OAuth tokens are accepted** (verified 2026-07-06): `/auth` and `/macro/get-schema` work with a customer token on projects that token can access. `ai_endpoints_allowed: false` for non-employees — the `ai-*` family stays employee-only.
+- **Every POST body** should include `client_id: "dungeon-master"` and `region` (`US` default).
+- **`/auth` accessibility ≠ data access.** `/auth {project_id}` can report `accessible: true` while `get-schema`/`query/*` on the same project return `HTTP 403: Forbidden` (token lacks data-level access, e.g. an employee token on a customer project). Diagnose with `/auth`, but don't trust it for data endpoints. Prefer the token of an actual project member.
+
+## Tools in this skill
+
+### `pt.mjs` — ad-hoc client
+
+```bash
+node .claude/skills/powertools/pt.mjs <path> ['<json-body>'] [--bearer <token>] [--get] [--region US]
+# examples
+node .claude/skills/powertools/pt.mjs /auth '{}'
+node .claude/skills/powertools/pt.mjs /macro/get-schema '{"project_id":"123","include_metadata":true,"verbose":true}'
+node .claude/skills/powertools/pt.mjs /query/getTopEvents --get          # docs, no auth
+```
+
+Bearer defaults to `.env` `BEARER_TOKEN`. Merges `client_id`/`region` into the body. Prints pretty JSON to stdout.
+
+### `snapshot-project.mjs` — schema + relative-volume snapshot
+
+```bash
+node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token> \
+  [--region US] [--out snapshot.json]
+```
+
+- Uses `/macro/get-schema` (`include_metadata` + `verbose`) + `/query/getTopEvents`. Token (customer or employee) needs data access to the project.
+- Output shape: `{ projectId, projectName, fetchedAt, totalCount, events: [{ name, count, pct, properties: [{name, type, description}] }], userProps: [{name, type, description}], groups: {} }`, events sorted by count desc.
+- **Never captures property values** — schema + volumes only. Snapshots stay privacy-safe by construction.
+
+## Endpoint catalog (the useful subset)
+
+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`).
+
+**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.
+
+**macros** — `/macro/get-schema` (always pass `include_metadata: true, verbose: true`; also `include_density: true` for per-(event,property) coverage % and `include_sdk_defaults: true` to keep `$browser`/`$os`-style SDK props — needed for carbon copies), `/macro/analyze-project` (volumes + cardinality + activity), `/macro/enumerate-project`, `/macro/clone-project`, `/macro/clone-boards`, `/macro/delete-entities`, `/macro/dungeon-master` (runs a dungeon config server-side and ingests), `/macro/ai-e2e-dm4` (demo build from a supplied schema, designed for dungeon-master), plus the `ai-*` family (dashboards, cohorts, metrics, schema naming).
+
+### get-schema field notes (verified on a 2,410-event project, 2026-07-06)
+
+- Response nests under `json`: `{ json: { events, properties, users, groups, dependencies }, duration_ms }`. Large projects are slow — 2,410 events took ~13 min; run it in the background.
+- Event counts include custom events (`customEventId > 0`) and merged events. Filter `!merged && !(customEventId > 0)` to match the Lexicon UI event count.
+- `properties` includes `mp_*` internals and `$custom_property:<id>` computed-prop references — exclude both when authoring a dungeon (ingestion stamps `mp_*` itself; computed props can't be tracked).
+- `exampleValue` fields contain REAL customer values — never copy them into a dungeon.
+- **Known issue**: `dependencies` can come back empty (`{events:{},properties:{}}`) on large projects even with `verbose: true` + `include_density: true` — the bulk dependency call silently fails. Retry the call; per-event property mapping is unavailable until it succeeds.
+
+## Recipe: copy a prod project into a dungeon
+
+Goal: a purely synthetic dungeon with the same events/props/user-props and matching **relative** event volumes. Safe to share — no customer data.
+
+1. **Snapshot** the source project (`snapshot-project.mjs`, customer token unless the employee token has data access). Sanity-check event count + that counts are non-zero.
+2. **Author the dungeon** from the snapshot (schema-first, per repo hook rules):
+   - Take the top-N events covering ≥95% of total volume (`pct` cumsum); note dropped tail in the OVERVIEW comment.
+   - `weight` per event ∝ snapshot `count` (normalize so max ≈ 100, min ≥ 1).
+   - Properties per event from snapshot; **invent all values** from name/type/description — never copy real values.
+   - `userProps` from snapshot; shared high-frequency props → `superProps`.
+   - Funnels: best-effort from event-name semantics (or `/query/listFunnels` + `/query/getFunnel` on the source if accessible).
+3. **Provision** into our org via the create-project skill: `node .claude/skills/create-project/provision.mjs <dungeon> --dry-run` → confirm → live. Uses `.env` `BEARER_TOKEN` + `ORG_ID`, writes `credentials` back into the dungeon.
+4. **Run**: `node scripts/run-dungeon.mjs <dungeon>`.
+5. **Verify** relative volumes: top-10 generated events should rank in the same order as the snapshot's top-10.

package/.claude/skills/powertools/pt.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * pt.mjs — thin ad-hoc client for the Mixpanel Power Tools API.
+ *
+ * Usage:
+ *   node .claude/skills/powertools/pt.mjs <path> ['<json-body>'] [--bearer <token>] [--get] [--region US]
+ *
+ * Examples:
+ *   node .claude/skills/powertools/pt.mjs /auth '{}'
+ *   node .claude/skills/powertools/pt.mjs /macro/get-schema '{"project_id":"123","include_metadata":true,"verbose":true}'
+ *   node .claude/skills/powertools/pt.mjs /query/getTopEvents --get     # endpoint docs, no auth
+ *
+ * POST bodies are merged with { client_id: "dungeon-master", region }.
+ * Bearer defaults to BEARER_TOKEN in the repo .env (employee OAuth). Customer
+ * OAuth tokens are accepted on non-ai endpoints; the ai-* family is
+ * employee-only (see SKILL.md).
+ */
+
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: resolve(__dirname, '../../../.env') });
+
+const BASE = 'https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app';
+const CLIENT_ID = 'dungeon-master';
+
+const args = process.argv.slice(2);
+const getMode = popFlag('--get');
+const bearer = popOpt('--bearer') ?? process.env.BEARER_TOKEN;
+const region = popOpt('--region') ?? 'US';
+const [pathArg, bodyArg] = args;
+
+if (!pathArg || !pathArg.startsWith('/')) {
+	console.error('Usage: node pt.mjs <path starting with /> [\'<json-body>\'] [--bearer <token>] [--get] [--region US]');
+	process.exit(1);
+}
+
+if (getMode) {
+	const res = await fetch(BASE + pathArg);
+	console.log(JSON.stringify(await res.json(), null, 2));
+	process.exit(res.ok ? 0 : 1);
+}
+
+if (!bearer) {
+	console.error('No bearer token: pass --bearer or set BEARER_TOKEN in .env');
+	process.exit(1);
+}
+
+let body = {};
+if (bodyArg) {
+	try {
+		body = JSON.parse(bodyArg);
+	} catch (err) {
+		console.error(`Body is not valid JSON: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+const res = await fetch(BASE + pathArg, {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+	body: JSON.stringify({ client_id: CLIENT_ID, region, ...body }),
+});
+
+const text = await res.text();
+try {
+	console.log(JSON.stringify(JSON.parse(text), null, 2));
+} catch {
+	console.log(text);
+}
+if (!res.ok) {
+	console.error(`\nHTTP ${res.status} ${res.statusText}`);
+	process.exit(1);
+}
+
+function popFlag(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return false;
+	args.splice(i, 1);
+	return true;
+}
+
+function popOpt(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return undefined;
+	const [, value] = args.splice(i, 2);
+	return value;
+}

package/.claude/skills/powertools/snapshot-project.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * snapshot-project.mjs — export a Mixpanel project's schema + relative event
+ * volumes into one normalized JSON snapshot, for authoring a synthetic
+ * dungeon-master "copy" of the project.
+ *
+ * Usage:
+ *   node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token> \
+ *     [--region US|EU|IN] [--out <file>]
+ *
+ * Uses the Power Tools API: /macro/get-schema (include_metadata + verbose) +
+ * /query/getTopEvents. The bearer token (customer or employee OAuth) needs
+ * data access to the project — /auth reporting accessible: true is not enough.
+ *
+ * Output shape (events sorted by count desc):
+ *   {
+ *     projectId, projectName, fetchedAt, region, totalCount,
+ *     events:    [{ name, count, pct, properties: [{ name, type, description }] }],
+ *     userProps: [{ name, type, description }],
+ *     groups:    {}
+ *   }
+ *
+ * Privacy: captures schema + volumes ONLY — never property values.
+ */
+
+import { writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: resolve(__dirname, '../../../.env') });
+
+const PT_BASE = 'https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app';
+const CLIENT_ID = 'dungeon-master';
+const REGIONS = ['US', 'EU', 'IN'];
+
+const args = process.argv.slice(2);
+const bearer = popOpt('--bearer') ?? process.env.BEARER_TOKEN;
+const region = (popOpt('--region') ?? 'US').toUpperCase();
+const outArg = popOpt('--out');
+const projectId = args.find((a) => !a.startsWith('--'));
+
+if (!projectId || !/^\d+$/.test(projectId)) fail('Usage: snapshot-project.mjs <project_id> --bearer <token> [--region US] [--out file]');
+if (!bearer) fail('No bearer token: pass --bearer or set BEARER_TOKEN in .env');
+if (!REGIONS.includes(region)) fail(`Unknown --region "${region}"`);
+
+const outPath = resolve(process.cwd(), outArg ?? `snapshot-${projectId}.json`);
+
+const snapshot = await snapshotViaPowertools();
+
+snapshot.events.sort((a, b) => b.count - a.count);
+snapshot.totalCount = snapshot.events.reduce((s, e) => s + e.count, 0);
+for (const e of snapshot.events) e.pct = snapshot.totalCount ? +(e.count / snapshot.totalCount * 100).toFixed(4) : 0;
+
+writeFileSync(outPath, JSON.stringify(snapshot, null, 2));
+
+const zeros = snapshot.events.filter((e) => e.count === 0).length;
+console.log(`✓ snapshot → ${outPath}`);
+console.log(`  project:    ${snapshot.projectName ?? '(name unknown)'} (${snapshot.projectId})`);
+console.log(`  events:     ${snapshot.events.length} (${zeros} with zero volume)`);
+console.log(`  userProps:  ${snapshot.userProps.length}`);
+console.log(`  total vol:  ${snapshot.totalCount.toLocaleString()} events`);
+console.log('  top 10:');
+for (const e of snapshot.events.slice(0, 10)) console.log(`    ${e.pct.toFixed(2).padStart(6)}%  ${e.count.toLocaleString().padStart(12)}  ${e.name}`);
+
+async function snapshotViaPowertools() {
+	const schema = await ptPost('/macro/get-schema', { project_id: projectId, include_metadata: true, verbose: true });
+	const top = await ptPost('/query/getTopEvents', { project_id: projectId, limit: 500 });
+
+	const counts = {};
+	for (const r of top.results ?? []) counts[r.event] = r.count;
+
+	// dependencies.events maps eventName → [propertyNames]; property defs live in schema.properties
+	const propDefs = new Map();
+	for (const p of schema.properties ?? []) propDefs.set(p.name, p);
+	const deps = schema.dependencies?.events ?? {};
+
+	const events = (schema.events ?? []).map((ev) => {
+		const name = ev.name ?? ev;
+		const propNames = deps[name] ?? [];
+		return {
+			name,
+			count: counts[name] ?? 0,
+			pct: 0,
+			properties: propNames.map((pn) => {
+				const def = propDefs.get(pn) ?? {};
+				return { name: pn, type: def.type ?? 'string', description: def.description ?? '' };
+			}),
+		};
+	});
+
+	const userProps = (schema.users ?? []).map((p) => ({
+		name: p.name ?? p,
+		type: p.type ?? 'string',
+		description: p.description ?? '',
+	}));
+
+	return { projectId, projectName: null, fetchedAt: new Date().toISOString(), region, totalCount: 0, events, userProps, groups: schema.groups ?? {} };
+}
+
+async function ptPost(pathname, body) {
+	const res = await fetch(PT_BASE + pathname, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+		body: JSON.stringify({ client_id: CLIENT_ID, region, ...body }),
+	});
+	const json = await res.json().catch(() => ({}));
+	if (!res.ok) throw new Error(`POST ${pathname} → HTTP ${res.status}: ${json.error ?? JSON.stringify(json).slice(0, 300)}`);
+	return json;
+}
+
+function popOpt(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return undefined;
+	const [, value] = args.splice(i, 2);
+	return value;
+}
+
+function fail(msg) {
+	console.error(`✖ ${msg}`);
+	process.exit(1);
+}

package/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 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
+
+- **Unweighted string arrays now produce stable power-law distributions**
+  (the long-documented intent finally works). Previously `choose()` rolled a
+  fresh random winner on every event — two compounding bugs (`!mostChosenIndex`
+  discarding an explicit `0`, plus a fresh `pickAWinner` closure per event) —
+  so aggregate breakdowns came out uniform (±edge noise). Now any plain array
+  of 3–19 unique strings gets ONE seed-deterministic winner per array per run,
+  drawn as ~45% winner / ~25% second / ~15% third / geometric-decay tail
+  (`winnerWeights` in `lib/utils/utils.js` is the single tuning point).
+  - Existing opt-outs unchanged: arrays containing
+    `variant`/`group`/`experiment`/`population`, arrays with explicit
+    duplicate entries (dupes honored exactly), arrays of length ≤2 or ≥20,
+    and non-string values.
+  - Direct `u.pickAWinner([...])` use in dungeon files gets the same stable
+    memoized winner for the run; explicit `pickAWinner(arr, 0)` is honored now.
+    (Note: `pickAWinner` calls at module-import time in dungeon files execute
+    before the run's seed is applied — as before — so those winners are stable
+    within a run but not pinned across processes.) Each `pickAWinner` resolver
+    now also carries its own expansion — previously `choose()`'s resolver cache
+    keyed by function source could serve one property's value list to a
+    different property.
+  - UTM properties (`utm_campaign` etc.) draw through the same path, so
+    campaign values now skew realistically per network instead of splitting
+    uniformly.
+  - New `resetValueCaches()` clears the per-run winner memo (and the
+    weighted-array resolver cache, which previously leaked across in-process
+    runs); called automatically by `initChance()` and at every run start.
+  - Side effect: ~1 RNG draw per string-array property per event instead of
+    ~30, and the seeded RNG stream shifts vs 1.6.0 — same seed no longer
+    reproduces 1.6.0 output byte-for-byte (within-version determinism is
+    unchanged).
+- **Engine-shape canary and hook-pattern integration tests made truly
+  deterministic** — their generating tests now run `describe.sequential`,
+  since concurrent in-process `generate()` calls interleave draws (and
+  re-seeds) on the shared seeded chance. The hook-pattern negative control
+  was recalibrated to 600 users; at 150 it exceeded its own threshold on
+  1.6.0 too and only passed under one lucky interleaving.
+
 ## 1.6.0 — 2026-07-04
 
 ### Added

package/README.md

@@ -155,6 +155,8 @@ 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.
+
 ### named exports
 
 alongside the default `DUNGEON_MASTER` export, the package root exports loader + interop helpers:

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,
 });

package/dungeons/vertical/fintech/fintech.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 './fintech.js';
 
 const PREFIX = process.argv[2] || 'verify-fintech';
@@ -51,11 +51,11 @@ const runSql = async (sql) => {
 	return stdout.trim() ? JSON.parse(stdout) : [];
 };
 
-// funnels passed raw (unvalidated) — every timeToConvert story carries an
-// explicit conversionWindowMs, 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,
 });