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

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,47 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 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/index.js

@@ -27,7 +27,7 @@ import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance, initUserChance, resetUserChance, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
+import { initChance, initUserChance, resetUserChance, resetValueCaches, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
 import { runWithDataset } from './lib/utils/dataset-context.js';
 
 // External dependencies
@@ -130,6 +130,10 @@ async function runDungeon(config) {
 		// Initialize seeded RNG BEFORE validation — config-validator captures a
 		// chance reference for default userProps (spiritAnimal). If we init after,
 		// run 1 binds an unseeded instance while run 2 binds a stale one → non-deterministic.
+		// v1.6.1: clear per-run winner/weighted-array caches unconditionally —
+		// a prior in-process run must never leak its winners into this one.
+		// (initChance also clears them, but only fires when a seed is set.)
+		resetValueCaches();
 		if (config.seed) {
 			initChance(config.seed);
 		}

package/lib/utils/utils.js

@@ -36,9 +36,35 @@ let globalUserChance;
 let userChanceInitialized = false;
 
 // Module-scoped memoization cache for weighted-array resolvers in `choose()`.
-// Lives for the lifetime of the node process; key is the function source string.
+// Key is the function source string; cleared per run by resetValueCaches().
+// Functions tagged `noCache = true` (e.g. pickAWinner closures, whose source
+// strings are identical across instances) bypass this cache entirely.
 const weightedArrayCache = new Map();
 
+// v1.6.1: per-run winner memo for unweighted string arrays. Two layers:
+// a WeakMap keyed by array IDENTITY holding the full {idx, weights} entry
+// (property arrays are stable references across a run, so the steady state is
+// a single WeakMap hit per event — no join, no weight rebuild), plus a Map
+// keyed by array CONTENTS so distinct array instances with equal contents
+// share one winner. Guarantees ONE stable winner per array per run so
+// aggregate distributions stay visibly skewed instead of cancelling to
+// uniform. Cleared by resetValueCaches() at run start / initChance so winners
+// never leak across runs or seeds.
+let winnerEntryCache = new WeakMap();
+const winnerCache = new Map();
+
+/**
+ * Clear the per-run value-resolution caches (winner memo + weighted-array
+ * resolver cache). Called by initChance() and at the top of every runDungeon
+ * so in-process back-to-back runs (different seeds, different users) never
+ * inherit a prior run's winners.
+ */
+function resetValueCaches() {
+	winnerEntryCache = new WeakMap();
+	winnerCache.clear();
+	weightedArrayCache.clear();
+}
+
 // v1.5.1: dataset-window state moved to AsyncLocalStorage scope
 // (`lib/utils/dataset-context.js`). Each `generate()` call wraps the pipeline
 // in `runWithDataset(begin, now, fn)`, and factory thunks read via the
@@ -146,6 +172,7 @@ function initChance(seed) {
 	if (!seed && process.env.SEED) seed = process.env.SEED;
 	globalChance = new Chance(seed);
 	chanceInitialized = true;
+	resetValueCaches();
 	return globalChance;
 }
 
@@ -387,10 +414,10 @@ function choose(value) {
 			// check to make sure that each element in the array only occurs once...
 			const uniqueItems = new Set(value);
 			if (uniqueItems.size === value.length) {
-				// Array has no duplicates, use pickAWinner
-				const quickList = pickAWinner(value, 0)();
-				const theChosenOne = chance.pickone(quickList);
-				return theChosenOne;
+				// Array has no duplicates → power-law draw with ONE stable
+				// seed-deterministic winner per array per run (v1.6.1)
+				const entry = getWinnerEntry(/** @type {string[]} */ (value));
+				return chance.weighted(value, entry.weights);
 			}
 
 		}
@@ -408,8 +435,17 @@ function choose(value) {
 	}
 
 	try {
-		// Keep resolving the value if it's a function (with caching)
+		// Keep resolving the value if it's a function (with caching).
+		// Functions tagged noCache (pickAWinner closures) skip the source-string
+		// cache: their toString() is identical across instances, so caching by
+		// source would hand one property's expansion to every other property.
 		while (typeof value === 'function') {
+			if (/** @type {any} */ (value).noCache === true) {
+				const result = value();
+				if (result instanceof ListValue) return result;
+				value = result;
+				continue;
+			}
 			const funcString = value.toString();
 
 			if (weightedArrayCache.has(funcString)) {
@@ -452,11 +488,6 @@ function choose(value) {
 			}
 		}
 
-		// ["","",""] should pick-a-winner
-		if (Array.isArray(value) && typeof value[0] === "string") {
-			value = pickAWinner(value)();
-		}
-
 		// [0,1,2] should pick one
 		if (Array.isArray(value) && typeof value[0] === "number") {
 			return chance.pickone(value);
@@ -988,63 +1019,122 @@ function weighChoices(items) {
 	};
 }
 
+/**
+ * Resolve the stable per-run winner index for an array of items. Memoized in
+ * `winnerCache` keyed by array contents (raw joined string — no hashing, so
+ * no collision risk), so every event drawing from the same array favors the
+ * SAME winner for the whole run. Winner is rolled from the seeded chance →
+ * same seed = same winner; resetValueCaches() clears the memo between runs.
+ *
+ * @param {Array} items - The list of items to pick a winner from.
+ * @returns {number} - The stable winner index for this run.
+ */
+function getStableWinnerIndex(items) {
+	const key = items.join('\u0000');
+	if (winnerCache.has(key)) return winnerCache.get(key);
+	const chance = getChance();
+	const winner = chance.integer({ min: 0, max: items.length - 1 });
+	winnerCache.set(key, winner);
+	return winner;
+}
+
+/**
+ * Full winner entry ({idx, weights}) for an array, memoized by array identity
+ * in a WeakMap. Steady state for the choose() hot path is one WeakMap hit per
+ * event — no join, no weight rebuild. Distinct array instances with equal
+ * contents converge on the same winner via getStableWinnerIndex.
+ *
+ * @param {string[]} items
+ * @returns {{idx: number, weights: number[]}}
+ */
+function getWinnerEntry(items) {
+	let entry = winnerEntryCache.get(items);
+	if (entry) return entry;
+	const idx = getStableWinnerIndex(items);
+	entry = { idx, weights: winnerWeights(items.length, idx) };
+	winnerEntryCache.set(items, entry);
+	return entry;
+}
+
+/**
+ * Build a power-law weight vector aligned to item indices: winner ~45%,
+ * second ~25%, third ~15%, remainder split over the tail with geometric decay.
+ * Rank order follows the rotational convention: second = (winner+1) % n,
+ * third = (winner+2) % n. This is THE place to tune the curve.
+ *
+ * @param {number} n - Number of items.
+ * @param {number} winnerIndex - Index of the winning item.
+ * @returns {number[]} - Weights (unnormalized; chance.weighted normalizes).
+ */
+function winnerWeights(n, winnerIndex) {
+	if (n <= 0) return [];
+	if (n === 1) return [1];
+	const HEAD = [45, 25, 15];
+	const TAIL_BUDGET = 15;
+	const TAIL_DECAY = 0.7;
+	const tailCount = Math.max(0, n - HEAD.length);
+	let tailWeights = [];
+	if (tailCount > 0) {
+		const raw = [];
+		let w = 1;
+		for (let k = 0; k < tailCount; k++) { raw.push(w); w *= TAIL_DECAY; }
+		const sum = raw.reduce((a, b) => a + b, 0);
+		tailWeights = raw.map(r => (r / sum) * TAIL_BUDGET);
+	}
+	const weights = new Array(n).fill(0);
+	for (let rank = 0; rank < n; rank++) {
+		const idx = (winnerIndex + rank) % n;
+		weights[idx] = rank < HEAD.length ? HEAD[rank] : tailWeights[rank - HEAD.length];
+	}
+	return weights;
+}
+
 /**
  * Creates a function that generates a weighted list of items
  * with a higher likelihood of picking a specified index and clear second and third place indices.
- * 
+ *
+ * v1.6.1: the returned closure yields a DETERMINISTIC weighted expansion
+ * (winner ~45%, second ~25%, third ~15%, geometric tail) built once — no
+ * per-call sampling variance. When no index is passed, the winner is the
+ * stable per-run memoized winner for the array (see getStableWinnerIndex),
+ * so direct dungeon-file usage is stable and seed-deterministic too.
+ *
  * @param {Array} items - The list of items to pick from.
  * @param {number} [mostChosenIndex] - The index of the item to be most favored.
  * @returns {function} - A function that returns a weighted list of items.
  */
 function pickAWinner(items, mostChosenIndex) {
-	const chance = getChance();
-
-	// Ensure mostChosenIndex is within the bounds of the items array
 	if (!items) return () => { return ""; };
 	if (!items.length) return () => { return ""; };
-	if (!mostChosenIndex) mostChosenIndex = chance.integer({ min: 0, max: items.length - 1 });
-	if (mostChosenIndex >= items.length) mostChosenIndex = items.length - 1;
-
-	// Calculate second and third most chosen indices
-	const secondMostChosenIndex = (mostChosenIndex + 1) % items.length;
-	const thirdMostChosenIndex = (mostChosenIndex + 2) % items.length;
+	if (!Number.isFinite(mostChosenIndex)) {
+		// undefined/null/NaN → stable per-run memoized winner
+		mostChosenIndex = getStableWinnerIndex(items);
+	} else {
+		mostChosenIndex = Math.floor(mostChosenIndex);
+		if (mostChosenIndex >= items.length) mostChosenIndex = items.length - 1;
+		if (mostChosenIndex < 0) mostChosenIndex = 0;
+	}
 
-	// Return a function that generates a weighted list
-	return function () {
-		const weighted = [];
-		for (let i = 0; i < 10; i++) {
-			const rand = chance.d10(); // Random number between 1 and 10
-
-			// 35% chance to favor the most chosen index
-			if (chance.bool({ likelihood: 35 })) {
-				// 50% chance to slightly alter the index
-				if (chance.bool({ likelihood: 50 })) {
-					weighted.push(items[mostChosenIndex]);
-				} else {
-					const addOrSubtract = chance.bool({ likelihood: 50 }) ? -rand : rand;
-					let newIndex = mostChosenIndex + addOrSubtract;
+	const weights = winnerWeights(items.length, mostChosenIndex);
+	const total = weights.reduce((a, b) => a + b, 0);
+	// scale slots with n so large arrays keep the ~45% winner share instead of
+	// having Math.max(1, ...) floors dilute it
+	const SLOTS = Math.max(20, items.length * 4);
+	const expansion = [];
+	items.forEach((item, i) => {
+		// every item keeps at least one slot so no value becomes unreachable
+		const count = Math.max(1, Math.round((weights[i] / total) * SLOTS));
+		for (let j = 0; j < count; j++) expansion.push(item);
+	});
 
-					// Ensure newIndex is within bounds
-					if (newIndex < 0) newIndex = 0;
-					if (newIndex >= items.length) newIndex = items.length - 1;
-					weighted.push(items[newIndex]);
-				}
-			}
-			// 25% chance to favor the second most chosen index
-			else if (chance.bool({ likelihood: 25 })) {
-				weighted.push(items[secondMostChosenIndex]);
-			}
-			// 15% chance to favor the third most chosen index
-			else if (chance.bool({ likelihood: 15 })) {
-				weighted.push(items[thirdMostChosenIndex]);
-			}
-			// Otherwise, pick a random item from the list
-			else {
-				weighted.push(chance.pickone(items));
-			}
-		}
-		return weighted;
+	const resolver = function () {
+		return expansion;
 	};
+	// all pickAWinner closures share one source string; without this tag,
+	// choose()'s weightedArrayCache would cache the first closure's expansion
+	// under that shared key and serve it for every other pickAWinner property
+	resolver.noCache = true;
+	return resolver;
 }
 
 function quickHash(str, seed = 0) {
@@ -1774,6 +1864,7 @@ export {
 	getUniqueKeys,
 	person,
 	pickAWinner,
+	resetValueCaches,
 	quickHash,
 	weighArray,
 	validateEventConfig,

package/package.json

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

package/types.d.ts

@@ -2358,6 +2358,8 @@ declare module '@ak--47/dungeon-master/utils' {
     export function objectList(template: Record<string, ValueValid>, options?: { min?: number; max?: number }): () => Array<Record<string, unknown>>;
     export function weighNumRange(min: number, max: number, skew?: number, size?: number): number[];
     export function pickAWinner(items: string[], mostChosenIndex?: number): () => string[];
+    /** Clears the per-run stable-winner + weighted-array caches (also called by initChance and at every run start). */
+    export function resetValueCaches(): void;
     export function initChance(seed?: string): unknown;
     export function initUserChance(seed?: string): unknown;
     export function getUserChance(): unknown;