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

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;
 }
 
@@ -289,8 +316,8 @@ function datesBetween(start, end) {
 
 /**
  * returns a random date
- * @param  {any} start
- * @param  {any} end
+ * @param  {string | number | Date | dayjs.Dayjs | null} [start]
+ * @param  {string | number | Date | dayjs.Dayjs | null} [end]
  */
 function day(start, end) {
 	const chance = getChance();
@@ -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);
 			}
 
 		}
@@ -399,16 +426,26 @@ function choose(value) {
 
 	// if the thing has a .next() method, call that (e.g., generators/iterators)
 	try {
-		if (value && typeof /** @type {any} */ (value).next === 'function') {
-			return /** @type {any} */ (value).next();
+		const iterCandidate = /** @type {{ next?: unknown }} */ (/** @type {unknown} */ (value));
+		if (value && typeof iterCandidate.next === 'function') {
+			return iterCandidate.next();
 		}
 	} catch (e) {
 		console.error(`Error occurred while calling next(): ${e}`);
 	}
 
 	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)) {
@@ -451,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);
@@ -987,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) {
@@ -1773,6 +1864,7 @@ export {
 	getUniqueKeys,
 	person,
 	pickAWinner,
+	resetValueCaches,
 	quickHash,
 	weighArray,
 	validateEventConfig,

package/lib/verify/coerce.js

@@ -0,0 +1,186 @@
+/**
+ * Shared value-coercion + filter-comparison helpers matching Mixpanel's ARB
+ * engine semantics. Two DIFFERENT rulebooks live here — do not mix them up:
+ *
+ * 1. SEGMENT IDENTITY (breakdown bucketing) is case-SENSITIVE and type-tagged.
+ *    ARB hashes the raw typed value: strings hash their raw bytes with no case
+ *    folding (hash_value.c:114-115 → hash_string_value_with_seed, raw XXH3
+ *    over strlen bytes), and segment ordering uses arb_strcmp (cmp.c:24-32).
+ *    Each value type mixes a distinct tag into the hash (number_tag,
+ *    string_tag, true/false_tag — hash_value.c:92-97), so the number 1 and
+ *    the string "1" are DIFFERENT segments even though both display as "1".
+ *
+ * 2. WHERE-FILTER string comparison is case-INSENSITIVE. value_equal uses
+ *    arb_strcasecmp (value.c:285), `contains` uses arb_strcaseinstr
+ *    (eval_node.c:2914), and string relational operators use arb_strcasecmp
+ *    (eval_node.c:2931). The filter helpers below implement that rulebook and
+ *    must NEVER be used to bucket breakdown segments.
+ */
+
+/**
+ * Coerce a property value to its Mixpanel display/bucket label.
+ *
+ * - `null` and `undefined` both become the literal string "undefined" — the
+ *   string-typecast default (`string(prop, "undefined")`) that produces the
+ *   "undefined" segment in every Insights breakdown (arb_selector.py:889-916).
+ * - Booleans → "true"/"false"; numbers → decimal string with -0 normalized to
+ *   0 (hash_value.c:111 `v.d = v.d == -0.0 ? 0.0 : v.d`).
+ * - Strings pass through UNCHANGED — case-preserving (rulebook 1 above).
+ * - Objects JSON-stringify (rare; ARB hashes structurally — hash_object).
+ * - Lists are NOT handled here: callers fan out per item (ACTION_TYPE_FOR_EACH,
+ *   normal_query.cpp:1718-1776) before coercing each item.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+export function coerceToBreakdownKey(value) {
+	if (value === null || value === undefined) return 'undefined';
+	if (typeof value === 'boolean') return value ? 'true' : 'false';
+	if (typeof value === 'number') return String(Object.is(value, -0) ? 0 : value);
+	if (typeof value === 'string') return value;
+	return JSON.stringify(value);
+}
+
+/**
+ * Internal segment-identity key: type-tagged so number 1 ≠ string "1"
+ * (hash_value.c type tag mixins). Case-preserving for strings.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+export function breakdownSegmentKey(value) {
+	if (value === null || value === undefined) return 'u:';
+	if (typeof value === 'boolean') return `b:${value}`;
+	if (typeof value === 'number') return `n:${Object.is(value, -0) ? 0 : value}`;
+	if (typeof value === 'string') return `s:${value}`;
+	return `o:${JSON.stringify(value)}`;
+}
+
+/**
+ * WHERE-filter equality. Strings compare case-insensitively
+ * (value.c:285 — value_equal → arb_strcasecmp). null == null and
+ * undefined == undefined are each equal (value.c VALUE_TYPE_UNDEFINED/NULL
+ * cases return equal=true) but null != undefined (type mismatch short-circuits
+ * before the switch). Cross-type comparisons are never equal.
+ *
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean}
+ */
+export function filterEquals(a, b) {
+	if (typeof a === 'string' && typeof b === 'string') {
+		return a.toLowerCase() === b.toLowerCase();
+	}
+	if (a === null || a === undefined || b === null || b === undefined) {
+		return a === b || (a === null && b === null) || (a === undefined && b === undefined);
+	}
+	return a === b;
+}
+
+/**
+ * WHERE-filter relational comparison for two strings, case-insensitive
+ * (eval_node.c:2931 — string relational operators go through arb_strcasecmp).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative / 0 / positive like strcmp
+ */
+export function filterCompare(a, b) {
+	const la = a.toLowerCase(), lb = b.toLowerCase();
+	return la < lb ? -1 : la > lb ? 1 : 0;
+}
+
+/**
+ * WHERE-filter substring test, case-insensitive
+ * (eval_node.c:2914 — BINARY_OPERATOR_IN uses arb_strcaseinstr).
+ *
+ * @param {string} haystack
+ * @param {string} needle
+ * @returns {boolean}
+ */
+export function filterContains(haystack, needle) {
+	return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+
+/**
+ * List-valued property membership: ARB's BINARY_OPERATOR_IN with a LIST
+ * right operand walks the list and tests per-item value_equal
+ * (eval_node.c:2949-2959) — typed equality, case-insensitive for strings
+ * (value.c:285). This is the ONLY list operator the query builder emits for
+ * list-typed properties ("contains"/"does not contain" compile to in/not-in;
+ * LIST_CONTAINS_STRING is never generated by the API layer). Substring
+ * matching does NOT apply per item.
+ *
+ * @param {Array<*>} list
+ * @param {*} needle
+ * @returns {boolean}
+ */
+function listMembership(list, needle) {
+	return list.some(item => filterEquals(item, needle));
+}
+
+/**
+ * Evaluate a `where` filter object against a flat record using the
+ * WHERE-filter rulebook (case-insensitive strings). Shape mirrors funnel step
+ * filters: `{ prop: value }` (equality) or `{ prop: { op, value } }` with
+ * op ∈ eq | neq | gt | lt | gte | lte | contains | not_contains.
+ *
+ * Relational ops: numbers compare numerically, strings via filterCompare
+ * (eval_node.c:2870-2906 numeric branch, :2931 string branch). Mixed-type or
+ * null/undefined operands fail relational tests (value_cmp orders by type
+ * first — cross-type never satisfies a within-type comparison here).
+ *
+ * List-valued record properties: eq/contains test per-item membership and
+ * neq/not_contains its negation (see listMembership). Raw `==` on
+ * list-vs-scalar is a type-mismatch false in ARB, but the query builder never
+ * emits it for list props — it emits IN — so the DSL's bare `{ prop: value }`
+ * maps to membership rather than silently never matching. Relational ops on
+ * list values stay false (scalar-vs-list has no per-item relational in ARB).
+ *
+ * @param {Object} record flat event/profile record
+ * @param {Object<string, *>} [where]
+ * @returns {boolean}
+ */
+export function matchesWhere(record, where) {
+	if (!where) return true;
+	for (const [prop, cond] of Object.entries(where)) {
+		const actual = record[prop];
+		const { op, value } = (cond && typeof cond === 'object' && !Array.isArray(cond) && 'op' in cond)
+			? cond
+			: { op: 'eq', value: cond };
+		let pass;
+		switch (op) {
+			case 'eq':
+				pass = Array.isArray(actual) ? listMembership(actual, value) : filterEquals(actual, value);
+				break;
+			case 'neq':
+				pass = Array.isArray(actual) ? !listMembership(actual, value) : !filterEquals(actual, value);
+				break;
+			case 'gt':
+			case 'lt':
+			case 'gte':
+			case 'lte': {
+				let cmp;
+				if (typeof actual === 'number' && typeof value === 'number') cmp = actual - value;
+				else if (typeof actual === 'string' && typeof value === 'string') cmp = filterCompare(actual, value);
+				else { pass = false; break; }
+				pass = op === 'gt' ? cmp > 0 : op === 'lt' ? cmp < 0 : op === 'gte' ? cmp >= 0 : cmp <= 0;
+				break;
+			}
+			case 'contains':
+				pass = Array.isArray(actual)
+					? listMembership(actual, value) // membership, NOT per-item substring
+					: (typeof actual === 'string' && typeof value === 'string' && filterContains(actual, value));
+				break;
+			case 'not_contains':
+				pass = Array.isArray(actual)
+					? !listMembership(actual, value)
+					: !(typeof actual === 'string' && typeof value === 'string' && filterContains(actual, value));
+				break;
+			default:
+				throw new Error(`matchesWhere: unknown op "${op}"`);
+		}
+		if (!pass) return false;
+	}
+	return true;
+}