@ak--47/dungeon-master 1.6.4 → 1.7.0

package/lib/utils/conditions.js

@@ -0,0 +1,62 @@
+/**
+ * Funnel `conditions` matching (v1.7.0 — P0-1).
+ *
+ * A funnel with `conditions` is offered only to users whose profile satisfies
+ * every key (AND across keys). Each value is either:
+ *
+ *   - a scalar → strict equality (`profile[key] === value`), unchanged since 1.3
+ *   - an operator map → every operator in the map must hold (AND within a key)
+ *
+ * Operators: `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`.
+ * `in` / `nin` take arrays; the rest take scalars. `gt`/`gte`/`lt`/`lte` use
+ * JavaScript's `<` / `>` so numbers and ISO date strings both compare.
+ *
+ * A missing profile key never satisfies `eq`, `in`, or an ordering operator;
+ * it does satisfy `neq` and `nin` (the value is not the excluded one).
+ *
+ * The validator (`validateFunnelConditions`) rejects functions, bare arrays,
+ * unknown operators, and `in`/`nin` without an array — those shapes used to
+ * silently never match and hand the author an empty funnel.
+ */
+
+export const CONDITION_OPERATORS = Object.freeze(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']);
+const OPERATOR_SET = new Set(CONDITION_OPERATORS);
+
+/**
+ * True when `value` is an operator map (plain object, not array/Date).
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isOperatorMap(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+}
+
+/**
+ * @param {Record<string, unknown>} profile
+ * @param {Record<string, unknown>} conditions
+ * @returns {boolean}
+ */
+export function matchConditions(profile, conditions) {
+	if (!conditions) return true;
+	for (const [key, cond] of Object.entries(conditions)) {
+		const actual = profile ? profile[key] : undefined;
+		if (!isOperatorMap(cond)) {
+			if (actual !== cond) return false;
+			continue;
+		}
+		for (const [op, expected] of Object.entries(cond)) {
+			if (!OPERATOR_SET.has(op)) return false; // validator throws earlier; defensive
+			switch (op) {
+				case 'eq': if (actual !== expected) return false; break;
+				case 'neq': if (actual === expected) return false; break;
+				case 'in': if (!Array.isArray(expected) || !expected.includes(actual)) return false; break;
+				case 'nin': if (Array.isArray(expected) && expected.includes(actual)) return false; break;
+				case 'gt': if (!(/** @type {any} */ (actual) > /** @type {any} */ (expected))) return false; break;
+				case 'gte': if (!(/** @type {any} */ (actual) >= /** @type {any} */ (expected))) return false; break;
+				case 'lt': if (!(/** @type {any} */ (actual) < /** @type {any} */ (expected))) return false; break;
+				case 'lte': if (!(/** @type {any} */ (actual) <= /** @type {any} */ (expected))) return false; break;
+			}
+		}
+	}
+	return true;
+}

package/lib/utils/json-evaluator.js

@@ -48,9 +48,19 @@ export function evaluateFunctionCall(funcCall) {
 
 	const { functionName, args, body } = funcCall;
 
-	// Special handling for arrow functions
+	// Special handling for arrow functions.
+	// v1.7.0 (P1-1): emit `(ctx) => body` so serialized dungeons can read the
+	// value context (`ctx.profile`, `ctx.event`, `ctx.time`, `ctx.config`).
+	// Bodies that ignore `ctx` behave exactly as before.
 	if (functionName === 'arrow') {
-		return `() => ${body}`;
+		// `dungeon-to-json` stores a whole function source as the body
+		// (`(ctx) => ctx.profile.plan`, `function () { … }`). Emit it as-is so the
+		// revived value is that function, not a thunk returning it.
+		const trimmed = String(body).trim();
+		const isWholeFunction = /^(async\s+)?function\b/.test(trimmed)
+			|| /^(async\s*)?\([^)]*\)\s*=>/.test(trimmed)
+			|| /^(async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed);
+		return isWholeFunction ? `(${trimmed})` : `(ctx) => ${body}`;
 	}
 
 	// Handle chance.* functions

package/lib/utils/utils.js

@@ -63,6 +63,51 @@ function resetValueCaches() {
 	winnerEntryCache = new WeakMap();
 	winnerCache.clear();
 	weightedArrayCache.clear();
+	autoPowerLawEnabled = true;
+}
+
+// v1.7.0 (P2-1): run-level switch for the implicit power-law draw on 3–19-item
+// unique-string arrays. `choose()` is a free function with no config access, so
+// the orchestrator sets this from `validatedConfig.autoPowerLaw` at run start
+// (mirrors how the seeded chance singleton is managed). resetValueCaches()
+// restores the default so a prior run's opt-out never leaks.
+let autoPowerLawEnabled = true;
+
+/** @param {boolean} enabled */
+function setAutoPowerLaw(enabled) {
+	autoPowerLawEnabled = enabled !== false;
+}
+
+/** @returns {boolean} */
+function getAutoPowerLaw() {
+	return autoPowerLawEnabled;
+}
+
+/**
+ * v1.7.0 (P1-1): true for a value function that DECLARES a parameter (`(ctx) => …`)
+ * and is not a bound native (`chance.animal.bind(chance)` reports the native's
+ * arity but cannot read ctx). Context-aware functions skip the source-string
+ * cache and, on funnel steps, resolve inside makeEvent with the real event ctx.
+ * @param {unknown} value
+ * @returns {value is (ctx?: any) => any}
+ */
+function isContextAware(value) {
+	return typeof value === 'function' && value.length >= 1 && !Function.prototype.toString.call(value).includes('[native code]');
+}
+
+/**
+ * v1.7.0 (P2-1): `{ __weights: { free: 60, pro: 30, enterprise: 10 } }` — the
+ * declarative weighted form. True when `value` carries a non-empty `__weights`
+ * object whose values are finite, non-negative numbers.
+ * @param {unknown} value
+ * @returns {value is { __weights: Record<string, number> }}
+ */
+function isWeightsForm(value) {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+	const w = /** @type {any} */ (value).__weights;
+	if (!w || typeof w !== 'object' || Array.isArray(w)) return false;
+	const entries = Object.entries(w);
+	return entries.length > 0 && entries.every(([, n]) => typeof n === 'number' && Number.isFinite(n) && n >= 0);
 }
 
 // v1.5.1: dataset-window state moved to AsyncLocalStorage scope
@@ -400,15 +445,24 @@ function objectList(template, options = {}) {
  * similar to pick
  * @param  {ValueValid} value
  */
-function choose(value) {
+function choose(value, ctx = undefined) {
 	if (value instanceof ListValue) return value;
 	const chance = getChance();
 
-	// most of the time this will receive a list of strings; 
+	// v1.7.0 (P2-1): declarative weights. The author's numbers ARE the
+	// distribution — no power law, no winner memo. Zero-weight keys never draw.
+	if (isWeightsForm(value)) {
+		const entries = Object.entries(value.__weights).filter(([, n]) => n > 0);
+		if (!entries.length) return "";
+		return chance.weighted(entries.map(([k]) => k), entries.map(([, n]) => n));
+	}
+
+	// most of the time this will receive a list of strings;
 	// when that is the case, we need to ensure some 'keywords' like 'variant' or 'test' aren't in the array
 	// next we want to see if the array is unweighted ... i.e. no dupe strings and each string only occurs once ['a', 'b', 'c', 'd']
 	// if all these are true we will pickAWinner(value)()
-	if (Array.isArray(value) && value.length > 2 && value.length < 20 && value.every(item => typeof item === 'string')) {
+	// v1.7.0 (P2-1): `autoPowerLaw: false` skips this branch → uniform pickone below.
+	if (autoPowerLawEnabled && Array.isArray(value) && value.length > 2 && value.length < 20 && value.every(item => typeof item === 'string')) {
 		// ensure terms 'variant' 'group' 'experiment' or 'population' are NOT in any of the items
 		if (!value.some(item => item.includes('variant') || item.includes('group') || item.includes('experiment') || item.includes('population'))) {
 			// check to make sure that each element in the array only occurs once...
@@ -439,21 +493,32 @@ function choose(value) {
 		// 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.
+		//
+		// v1.7.0 (P1-1): value functions receive a `ValueContext` (`{ profile,
+		// event, time, config }`, members optional). Any function with declared
+		// arity >= 1 is context-aware and ALSO skips the source-string cache —
+		// its result legitimately differs per user/event, so caching by source
+		// would freeze the first evaluation and hand it to every later caller.
+		// Zero-arity functions keep the pre-1.7 cache behavior exactly.
 		while (typeof value === 'function') {
-			if (/** @type {any} */ (value).noCache === true) {
-				const result = value();
+			// Bound natives (`chance.animal.bind(chance)`) report the native's arity
+			// and cannot read ctx; call them exactly as before (no argument) so the
+			// options object chance methods take never sees the context.
+			const funcString = value.toString();
+			const isNative = funcString.includes('[native code]');
+			if (/** @type {any} */ (value).noCache === true || (value.length >= 1 && !isNative)) {
+				const result = isNative ? value() : value(ctx);
 				if (result instanceof ListValue) return result;
 				value = result;
 				continue;
 			}
-			const funcString = value.toString();
 
 			if (weightedArrayCache.has(funcString)) {
 				value = weightedArrayCache.get(funcString);
 				break;
 			}
 
-			const result = value();
+			const result = isNative ? value() : value(ctx);
 			if (result instanceof ListValue) return result;
 			if (Array.isArray(result) && result.length > 10) {
 				// Cache large arrays (likely weighted arrays)
@@ -463,6 +528,8 @@ function choose(value) {
 		}
 
 			if (value instanceof ListValue) return value;
+			// A function may return the weighted form.
+			if (isWeightsForm(value)) return choose(value, ctx);
 
 			if (Array.isArray(value) && value.length === 0) {
 			return ""; // Return empty string if the array is empty
@@ -1864,6 +1931,10 @@ export {
 	person,
 	pickAWinner,
 	resetValueCaches,
+	setAutoPowerLaw,
+	getAutoPowerLaw,
+	isWeightsForm,
+	isContextAware,
 	quickHash,
 	weighArray,
 	validateEventConfig,

package/lib/verify/schema-validator.js

@@ -41,6 +41,14 @@ export function deriveExpectedSchema(config) {
 		}
 	}
 
+	// v1.7.0 (P1-2): stickyEventProps are engine-stamped on every event of every
+	// user — legal on every event type, not flag stamping.
+	if (Array.isArray(config.stickyEventProps)) {
+		for (const key of config.stickyEventProps) {
+			if (typeof key === 'string' && key) globalKeys.add(key);
+		}
+	}
+
 	if (config.hasLocation) {
 		for (const k of LOCATION_KEYS) globalKeys.add(k);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.6.4",
+	"version": "1.7.0",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -48,15 +48,7 @@
 		"dungeon:run": "node ./scripts/run-dungeon.mjs",
 		"dungeon:to-json": "node ./scripts/dungeon-to-json.mjs",
 		"dungeon:from-json": "node ./scripts/json-to-dungeon.mjs",
-		"dungeon:schema": "node ./scripts/extract-dungeon-schema.mjs",
-		"kodiak:deploy": "gcloud builds submit --config dungeons/user/kodiak/cloudbuild.yaml",
-		"kodiak:plan": "node dungeons/user/kodiak/kickoff.mjs --plan-only",
-		"kodiak:smoke:local": "bash dungeons/user/kodiak/smoke-local.sh",
-		"kodiak:smoke": "node dungeons/user/kodiak/kickoff.mjs --total-events 1000000000 --chunk-cap 10",
-		"kodiak:generate": "node dungeons/user/kodiak/kickoff.mjs --no-wait",
-		"kodiak:status": "node dungeons/user/kodiak/status.mjs",
-		"kodiak:run": "bash dungeons/user/kodiak/run-all.sh",
-		"kodiak:load": "node dungeons/user/kodiak/load-bq.mjs --replace --no-wait"
+		"dungeon:schema": "node ./scripts/extract-dungeon-schema.mjs"
 	},
 	"repository": {
 		"type": "git",