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

package/lib/hook-patterns/frequency-by-frequency.js

@@ -6,8 +6,10 @@
  * Insights view shows a deliberate shape (e.g., users with 5–20 cohort events
  * have 2x the metric event count of users with <5).
  *
- * Mechanism: classify the user into a bin based on their `cohortEvent` count,
- * then `scaleEventCount(events, targetEvent, multipliers[bin])` to scale that
+ * Mechanism: classify the user into a bin from their `cohortEvent` activity —
+ * distinct calendar days by default (v1.6, matching Mixpanel's frequency axis;
+ * see `binByDistinctPeriods`), or total events with `binBy: 'events'` — then
+ * `scaleEventCount(events, targetEvent, multipliers[bin])` to scale that
  * user's count of the target event up or down.
  *
  * Identity & schema constraints:
@@ -19,6 +21,7 @@
  */
 
 import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { binByDistinctPeriods } from '../verify/counting.js';
 import { scaleEventCount } from '../hook-helpers/mutate.js';
 
 /**
@@ -30,14 +33,21 @@ import { scaleEventCount } from '../hook-helpers/mutate.js';
  * @param {string} opts.targetEvent - Event whose count is scaled per bin.
  * @param {Record<string, number>} opts.multipliers - Bin name → multiplier (1 = no-op,
  *   2 = double, 0.5 = halve). Bins absent from this map use multiplier 1.
+ * @param {('events'|'distinctDays')} [opts.binBy='distinctDays'] - Cohort axis.
+ *   `'distinctDays'` (default since v1.6) bins by distinct calendar days with
+ *   `cohortEvent` via `binByDistinctPeriods` — the axis Mixpanel's frequency
+ *   breakdown and the local emulator actually use. `'events'` restores the
+ *   pre-1.6 total-event-count axis.
  * @returns {{ bin: string|null, delta: number }} Bin assigned + signed delta from
  *   scaleEventCount (positive = clones added; negative = events dropped).
  */
-export function applyFrequencyByFrequency(events, _profile, { cohortEvent, bins, targetEvent, multipliers }) {
+export function applyFrequencyByFrequency(events, _profile, { cohortEvent, bins, targetEvent, multipliers, binBy = 'distinctDays' }) {
 	if (!events || !cohortEvent || !bins || !targetEvent || !multipliers) {
 		return { bin: null, delta: 0 };
 	}
-	const bin = binUsersByEventCount(events, cohortEvent, bins);
+	const bin = binBy === 'events'
+		? binUsersByEventCount(events, cohortEvent, bins)
+		: binByDistinctPeriods(events, cohortEvent, bins, 'day');
 	if (!bin) return { bin: null, delta: 0 };
 	const factor = multipliers[bin];
 	if (typeof factor !== 'number' || factor === 1) return { bin, delta: 0 };

package/lib/hook-patterns/funnel-frequency-breakdown.js

@@ -2,10 +2,11 @@
  * Pattern: Funnel Frequency Breakdown.
  *
  * Inside a `funnel-post` hook, vary the user's completion of the funnel by their
- * count of `cohortEvent` (anywhere in the dataset, not just the funnel). Used
- * when you want Mixpanel's funnel report — broken down by per-user count of an
- * activity event — to show e.g. "users who did 5+ X are 1.4x as likely to
- * complete this funnel."
+ * `cohortEvent` activity (anywhere in the dataset, not just the funnel) —
+ * distinct calendar days by default (v1.6), or total events with
+ * `binBy: 'events'`. Used when you want Mixpanel's funnel report — broken down
+ * by per-user frequency of an activity event — to show e.g. "users active 5+
+ * days with X are 1.4x as likely to complete this funnel."
  *
  * Mechanism: for users in a "drop-prone" bin, drop the funnel's final step
  * event(s) per the `dropMultipliers` config (1 = drop none, 0 = drop all).
@@ -15,13 +16,17 @@
  */
 
 import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { binByDistinctPeriods } from '../verify/counting.js';
 import { dropEventsWhere } from '../hook-helpers/mutate.js';
 
 /**
  * @param {Array<Object>} allUserEvents - Full per-user event history (read-only;
  *   used to count `cohortEvent`). When called inside `funnel-post`, derive this
  *   from `meta.profile` or pass the user's accumulated events from a closure.
- *   When `null`, falls back to counting cohortEvent inside `funnelEvents`.
+ *   When `null`, falls back to counting cohortEvent inside `funnelEvents` —
+ *   note the fallback makes the default `'distinctDays'` axis degenerate (a
+ *   single funnel run rarely spans more than one calendar day); pass
+ *   `binBy: 'events'` when only funnel events are available.
  * @param {Object} _profile
  * @param {Array<Object>} funnelEvents - Funnel events produced by `makeFunnel`
  *   (mutated in place).
@@ -32,15 +37,22 @@ import { dropEventsWhere } from '../hook-helpers/mutate.js';
  *   for the FINAL step event. 1 = always keep, 0 = always drop.
  * @param {string} [opts.finalStep] - Event name of the final step. Defaults to the
  *   last event in `funnelEvents` (in time order).
+ * @param {('events'|'distinctDays')} [opts.binBy='distinctDays'] - Cohort axis.
+ *   `'distinctDays'` (default since v1.6) bins by distinct calendar days with
+ *   `cohortEvent` via `binByDistinctPeriods` — the axis Mixpanel's funnel
+ *   frequency breakdown and the local emulator use. `'events'` restores the
+ *   pre-1.6 total-event-count axis.
  * @returns {{ bin: string|null, droppedFinal: boolean }}
  */
 export function applyFunnelFrequencyBreakdown(allUserEvents, _profile, funnelEvents, opts) {
-	const { cohortEvent, bins, dropMultipliers, finalStep } = opts || {};
+	const { cohortEvent, bins, dropMultipliers, finalStep, binBy = 'distinctDays' } = opts || {};
 	if (!funnelEvents || !cohortEvent || !bins || !dropMultipliers) {
 		return { bin: null, droppedFinal: false };
 	}
 	const sourceForBin = allUserEvents || funnelEvents;
-	const bin = binUsersByEventCount(sourceForBin, cohortEvent, bins);
+	const bin = binBy === 'events'
+		? binUsersByEventCount(sourceForBin, cohortEvent, bins)
+		: binByDistinctPeriods(sourceForBin, cohortEvent, bins, 'day');
 	if (!bin) return { bin: null, droppedFinal: false };
 	const keepRate = dropMultipliers[bin];
 	if (typeof keepRate !== 'number' || keepRate >= 1) return { bin, droppedFinal: false };
@@ -54,11 +66,11 @@ export function applyFunnelFrequencyBreakdown(allUserEvents, _profile, funnelEve
 	}
 	if (!stepName) return { bin, droppedFinal: false };
 
-	// Coin-flip drop using a deterministic-ish heuristic — this is called from a
-	// non-RNG context (funnel-post), so use Math.random would break determinism.
-	// Instead, use a hash on the funnel's first event's insert_id (deterministic
-	// per-call) modulo 1000 / 1000 vs. (1 - keepRate). For simplicity we use
-	// chance from utils when available.
+	// Deterministic drop decision without consuming the seeded RNG stream:
+	// hash the funnel's first insert_id (fallback: time) through
+	// simpleHashFloat — FNV-1a over the full string, quantized to 1/1000 —
+	// and drop when the hash lands under (1 - keepRate). Per-funnel stable,
+	// so reruns with the same seed drop the same funnels.
 	const dropProb = 1 - keepRate;
 	const seed = funnelEvents[0] && (funnelEvents[0].insert_id || funnelEvents[0].time) || '';
 	const det = simpleHashFloat(String(seed));

package/lib/hook-patterns/index.js

@@ -10,5 +10,5 @@
 export { applyFrequencyByFrequency } from './frequency-by-frequency.js';
 export { applyFunnelFrequencyBreakdown } from './funnel-frequency-breakdown.js';
 export { applyAggregateByBin } from './aggregate-per-user-by-bin.js';
-export { applyTTCBySegment } from './time-to-convert-by-segment.js';
+export { applyTTCBySegment, applyTTCBySegmentV2 } from './time-to-convert-by-segment.js';
 export { applyAttributedBySource } from './attributed-by-source.js';

package/lib/hook-patterns/time-to-convert-by-segment.js

@@ -1,25 +1,33 @@
 /**
  * Pattern: Time to Convert, broken down by user segment.
  *
- * Inside a `funnel-post` hook, scale the funnel's time-to-convert by a factor
- * keyed off of a user-profile property value (e.g., trial users convert 3x
- * slower than enterprise). Lets Mixpanel's TTC funnel report — broken down by
- * a profile property — show a deliberate spread.
+ * Two generations:
  *
- * Mechanism: read `profile[segmentKey]`, look up the multiplier in `factors`,
- * and `scaleFunnelTTC(funnelEvents, factor)`. The first event's time is the
- * anchor (unchanged); subsequent steps' offsets from it are scaled.
+ * - `applyTTCBySegmentV2` (v1.6, use this) — `everything` hook. Finds the
+ *   user's FIRST in-order occurrence of the funnel steps across their whole
+ *   stream and scales those gaps. This is the sequence Mixpanel's greedy
+ *   funnel engine actually measures (HOOKS.md §2.2 / recipe 4.14), so the
+ *   scaling shows up in the TTC report and in the local verifier.
  *
- * Caveat: Mixpanel's "Time to Convert" funnel report uses the time between the
- * FIRST event of step A and the FIRST event of step B per user, not the actual
- * gap inside any one funnel run. The scaled funnel run will reflect in TTC only
- * when this funnel is the user's first occurrence of those steps — which it is
- * for an `isFirstFunnel`. For usage funnels, document this caveat to authors.
+ * - `applyTTCBySegment` (deprecated) — `funnel-post` hook. Scales one funnel
+ *   run's internal gaps. Mixpanel's TTC uses the FIRST occurrence of each
+ *   step per user, not the gaps inside any one run — so for usage funnels
+ *   (and any run that isn't the user's first) the scaling never reaches the
+ *   report. Kept for compatibility; emits a one-time console warning.
  */
 
-import { scaleFunnelTTC } from '../hook-helpers/timing.js';
+import { scaleFunnelTTC, findFirstSequence } from '../hook-helpers/timing.js';
+
+let warnedDeprecated = false;
 
 /**
+ * @deprecated since v1.6 — use `applyTTCBySegmentV2` from an `everything`
+ * hook. This funnel-post variant scales gaps inside ONE funnel run, but
+ * Mixpanel's TTC report measures the FIRST occurrence of each step per user
+ * (greedy engine, HOOKS.md §2.2) — so unless the run happens to be the
+ * user's first occurrence of those steps (`isFirstFunnel`), the scaling
+ * never moves the report.
+ *
  * @param {Array<Object>} funnelEvents - Mutated in place.
  * @param {Object} profile - The user's profile (must contain `segmentKey`).
  * @param {Object} opts
@@ -28,6 +36,10 @@ import { scaleFunnelTTC } from '../hook-helpers/timing.js';
  * @returns {{ segmentValue: any, factor: number, shifted: number }}
  */
 export function applyTTCBySegment(funnelEvents, profile, { segmentKey, factors }) {
+	if (!warnedDeprecated) {
+		warnedDeprecated = true;
+		console.warn('[dungeon-master] applyTTCBySegment is deprecated — use applyTTCBySegmentV2 from an `everything` hook (funnel-post scaling only reaches Mixpanel TTC for isFirstFunnel runs). This warning fires once.');
+	}
 	if (!funnelEvents || !funnelEvents.length || !profile || !segmentKey || !factors) {
 		return { segmentValue: null, factor: 1, shifted: 0 };
 	}
@@ -39,3 +51,53 @@ export function applyTTCBySegment(funnelEvents, profile, { segmentKey, factors }
 	const shifted = scaleFunnelTTC(funnelEvents, factor);
 	return { segmentValue, factor, shifted };
 }
+
+/**
+ * Scale the user's funnel time-to-convert by a profile-segment factor —
+ * operating on the FIRST in-order occurrence of `steps` across the user's
+ * whole stream, which is what Mixpanel's greedy funnel engine measures
+ * (recipe 4.14). Call from the `everything` hook.
+ *
+ * Mechanism: `findFirstSequence(events, steps, maxGapMinutes)` locates the
+ * greedy first-occurrence chain; `scaleFunnelTTC` multiplies each matched
+ * step's offset from the first step by `factors[profile[segmentKey]]`. The
+ * anchor step's time is unchanged; only the matched step events move.
+ *
+ * Conversion-window caveat: a factor > 1 can push the final step past the
+ * funnel's `conversionWindowDays` cap, where Mixpanel's strict-`<` rule
+ * excludes the conversion entirely — clamp your factors the way recipe 4.28
+ * does when scaling up. Timestamp moves are session-safe in v1.6 (P2.1
+ * re-derives `session_id` after the everything hook).
+ *
+ * @param {Array<Object>} events - User's FULL event stream (mutated in place).
+ * @param {Object} profile - The user's profile (must contain `segmentKey`).
+ * @param {Object} opts
+ * @param {string} opts.segmentKey - Profile property name to look up.
+ * @param {Record<string, number>} opts.factors - Profile-value → TTC factor
+ *   (0.5 halves the TTC, 2 doubles it; 1 or missing = no-op).
+ * @param {string[]} opts.steps - Ordered funnel step event names.
+ * @param {number} [opts.maxGapMinutes=43200] - Max gap between CONSECUTIVE
+ *   matched steps, in minutes (default 30 days). NOTE this is a per-gap
+ *   bound, NOT Mixpanel's conversion window: Mixpanel's window caps the
+ *   TOTAL time from step 0 to the final step, so a k-step sequence matched
+ *   here can span up to (k−1) × maxGapMinutes — well past a same-length
+ *   conversion window. When targeting a funnel report, keep total intended
+ *   TTC (gaps × factor) under the funnel's `conversionWindowDays`.
+ * @returns {{ segmentValue: any, factor: number, shifted: number }} `shifted`
+ *   = number of step events whose timestamps moved (0 when the user has no
+ *   qualifying sequence or the factor is a no-op).
+ */
+export function applyTTCBySegmentV2(events, profile, { segmentKey, factors, steps, maxGapMinutes = 43200 }) {
+	if (!events || !events.length || !profile || !segmentKey || !factors || !Array.isArray(steps) || steps.length < 2) {
+		return { segmentValue: null, factor: 1, shifted: 0 };
+	}
+	const segmentValue = profile[segmentKey];
+	const factor = factors[segmentValue];
+	if (typeof factor !== 'number' || factor === 1) {
+		return { segmentValue, factor: 1, shifted: 0 };
+	}
+	const seq = findFirstSequence(events, steps, maxGapMinutes);
+	if (!seq) return { segmentValue, factor, shifted: 0 };
+	const shifted = scaleFunnelTTC(seq, factor);
+	return { segmentValue, factor, shifted };
+}

package/lib/orchestrators/user-loop.js

@@ -459,6 +459,7 @@ export async function userLoop(context) {
 
 			// ALL SUBSEQUENT EVENTS (funnels for converted users, standalone for all)
 			let userChurned = false;
+			let userChurnTimeMs = null; // P2.2: timestamp of the churn event that ended the user
 			const sessionTimeout = config.sessionTimeout || 30;
 
 			// Standalone identity stamping mode: pre-existing or post-auth users get both
@@ -600,6 +601,8 @@ export async function userLoop(context) {
 							const userReturns = returnLikelihood > 0 && chance.bool({ likelihood: returnLikelihood * 100 });
 							if (!userReturns) {
 								userChurned = true;
+								const t = typeof ev.time === 'string' ? Date.parse(ev.time) : Number(ev.time);
+								if (Number.isFinite(t)) userChurnTimeMs = t;
 								break;
 							}
 						}
@@ -611,6 +614,20 @@ export async function userLoop(context) {
 			// Remove events flagged as future timestamps (before dungeon hooks see them)
 			usersEvents = usersEvents.filter(e => !e._drop);
 
+			// v1.6 (P2.2): churn is a hard activity boundary. Breaking the budget
+			// loop stopped GENERATION, but already-generated events carry
+			// independent TimeSoup timestamps over a shuffled active-day plan — so
+			// churned users kept events dated after their churn. Filter to
+			// time <= churnTime (the churn event itself survives: its own
+			// timestamp satisfies <=).
+			if (userChurned && userChurnTimeMs !== null) {
+				usersEvents = usersEvents.filter(e => {
+					if (!e || !e.time) return true;
+					const t = typeof e.time === 'string' ? Date.parse(e.time) : Number(e.time);
+					return Number.isFinite(t) ? t <= userChurnTimeMs : true;
+				});
+			}
+
 			// Feature 3: Engagement decay — filter behavioral events
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
 			if (userDecay && userDecay.model !== 'none' && usersEvents.length > 0) {
@@ -751,6 +768,30 @@ export async function userLoop(context) {
 				console.warn(`⚠️  Dropped ${droppedFuture} future-dated event(s) for user ${distinct_id}`);
 			}
 
+			// v1.6 (P2.1): re-derive session_ids on the FINAL event set. The first
+			// assignSessionIds pass (above) runs before the everything hook so hooks
+			// can read session_id — but time-mutating hooks (TTC scaling, injected
+			// bursts) leave stale labels that disagree with what Mixpanel computes
+			// from timestamps at query time. Relabeling is deterministic: IDs hash
+			// from (userKey + first event time of the session), so sessions whose
+			// events didn't move keep their exact IDs. The per-session sticky-device
+			// rewrite is intentionally NOT re-run — device stamping is hook-visible
+			// identity state, and relabeling sessions must not mutate identity fields.
+			if (hasSessionIds && usersEvents.length > 0) {
+				// assignSessionIds requires ascending time order. Relabel over a
+				// sorted shallow copy so `autoSortAfterEverything: false` users keep
+				// their chosen array order — stamps land on the shared event objects.
+				const sortedView = [...usersEvents].sort((a, b) => {
+					const ta = (a && typeof a.time === 'string') ? Date.parse(a.time) : Number(a && a.time);
+					const tb = (b && typeof b.time === 'string') ? Date.parse(b.time) : Number(b && b.time);
+					if (!Number.isFinite(ta) && !Number.isFinite(tb)) return 0;
+					if (!Number.isFinite(ta)) return 1;
+					if (!Number.isFinite(tb)) return -1;
+					return ta - tb;
+				});
+				u.assignSessionIds(sortedView, sessionTimeout);
+			}
+
 			// Store all user data (skip profile push when a hook returned null
 			// for type='user' — see dropUserProfile above).
 			if (!dropUserProfile) {

package/lib/templates/story-spec.schema.json

@@ -0,0 +1,175 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://github.com/ak--47/dungeon-master/lib/templates/story-spec.schema.json",
+	"title": "Dungeon stories export (v1.6 story-spec)",
+	"description": "Schema for the `stories` named export of a JS dungeon file. Stories pin each engineered hook effect to a mechanical assertion over emulateBreakdown output (or a DuckDB SQL escape hatch), so verification is computed — not re-derived by an LLM. Verdict tiers per assertion: NAILED = observed within ±10% of target; STRONG = passes floor (or target when no floor); WEAK = fails floor but effect direction correct, or cohort < minCohort; NONE = no measurable effect / selection empty; INVERSE = effect direction opposite the assertion. Story verdict = worst assertion.",
+	"type": "array",
+	"minItems": 1,
+	"items": { "$ref": "#/definitions/story" },
+	"definitions": {
+		"story": {
+			"type": "object",
+			"required": ["id", "hook", "archetype", "narrative", "assertions"],
+			"additionalProperties": false,
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Unique story id, conventionally '<hook>-<slug>' (e.g. 'H3-fraud-bursts')."
+				},
+				"hook": {
+					"type": "string",
+					"pattern": "^(?:H|Hook\\s*)?\\d+$",
+					"description": "Numbered hook this story verifies — matches the dungeon's HOOK STORIES doc block ('H3' or 'Hook 3' styles)."
+				},
+				"archetype": {
+					"type": "string",
+					"enum": [
+						"cohort-count-scale",
+						"cohort-prop-scale",
+						"temporal-inflection",
+						"funnel-conversion-by-segment",
+						"funnel-ttc-by-segment",
+						"retention-divergence",
+						"frequency-sweet-spot",
+						"attribution-bias",
+						"experiment-lift",
+						"lifecycle-wave",
+						"path-share",
+						"session-shape",
+						"composition-drift",
+						"bespoke"
+					],
+					"description": "Closed enum of engineered-effect shapes, seeded from the corpus's real story types."
+				},
+				"narrative": {
+					"type": "string",
+					"minLength": 1,
+					"description": "One-to-three sentence human story the data tells."
+				},
+				"mixpanelReport": {
+					"type": "object",
+					"description": "Free-form report pointer for humans and /create-project — NOT interpreted by the runner."
+				},
+				"assertions": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/definitions/assertion" }
+				},
+				"intentionalDeviations": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Documented strict-bar / limitation notes (e.g. 'tail_ratio < 0.4 by design — churn story')."
+				}
+			}
+		},
+		"assertion": {
+			"type": "object",
+			"required": ["breakdown"],
+			"additionalProperties": false,
+			"anyOf": [
+				{ "required": ["expect"] },
+				{ "required": ["assert"] }
+			],
+			"properties": {
+				"breakdown": { "$ref": "#/definitions/breakdown" },
+				"select": {
+					"type": "object",
+					"minProperties": 1,
+					"description": "Named row-sets over the breakdown result rows. Keys are the names referenced by expect.metric.",
+					"propertyNames": { "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
+					"additionalProperties": {
+						"type": "object",
+						"required": ["where"],
+						"additionalProperties": false,
+						"properties": {
+							"where": {
+								"type": "object",
+								"minProperties": 1,
+								"description": "Column → value (equality) or { op, value } comparison. All clauses must match (AND).",
+								"additionalProperties": {
+									"oneOf": [
+										{ "type": ["string", "number", "boolean", "null"] },
+										{
+											"type": "object",
+											"required": ["op", "value"],
+											"additionalProperties": false,
+											"properties": {
+												"op": { "type": "string", "enum": ["==", "!=", ">=", "<=", ">", "<"] },
+												"value": { "type": ["string", "number", "boolean", "null"] }
+											}
+										}
+									]
+								}
+							}
+						}
+					}
+				},
+				"expect": { "$ref": "#/definitions/expect" },
+				"assert": {
+					"description": "JS-only escape hatch: (rows, ctx) => { pass, detail?, verdict? }. Function-valued — JSON Schema cannot validate it; every use requires a comment justifying why the declarative grammar can't express it. JSON dungeons cannot carry it (dungeon-to-json drops extra exports).",
+					"not": { "type": ["string", "number", "boolean", "array", "null"] }
+				},
+				"minCohort": {
+					"type": "number",
+					"exclusiveMinimum": 0,
+					"description": "Population floor — when any named selection's cohort is below this, the verdict caps at WEAK."
+				}
+			}
+		},
+		"breakdown": {
+			"type": "object",
+			"required": ["type"],
+			"properties": {
+				"type": { "type": "string", "minLength": 1 }
+			},
+			"if": {
+				"properties": { "type": { "const": "duckdb" } }
+			},
+			"then": {
+				"required": ["type", "sql"],
+				"properties": {
+					"type": { "const": "duckdb" },
+					"sql": {
+						"type": "string",
+						"minLength": 1,
+						"description": "DuckDB SQL escape hatch, for bespoke shapes only. The runner shells out to the `duckdb` CLI (no npm dep) and substitutes the literal token {{PREFIX}} with the run's data prefix path (e.g. data/verify-<name>), so globs read read_json_auto('{{PREFIX}}-EVENTS*.json'). Result rows feed select/expect like emulator rows. Disk mode only — skipped (with a warning) under --in-memory."
+					}
+				}
+			},
+			"else": {
+				"description": "Anything other than 'duckdb' is passed byte-compatible to emulateBreakdown / verifyDungeon (frequencyByFrequency, funnelFrequency, aggregatePerUser, timeToConvert, attributedBy, sessionMetrics, retention, distinctCount, eventBreakdown, uniques, lifecycle, topPaths)."
+			}
+		},
+		"expect": {
+			"type": "object",
+			"required": ["metric", "op", "target"],
+			"additionalProperties": false,
+			"properties": {
+				"metric": {
+					"type": "string",
+					"pattern": "^\\s*([A-Za-z_$][A-Za-z0-9_$]*\\.[A-Za-z_$][A-Za-z0-9_$]*|[0-9]+(?:\\.[0-9]+)?)(\\s*[/\\-]\\s*([A-Za-z_$][A-Za-z0-9_$]*\\.[A-Za-z_$][A-Za-z0-9_$]*|[0-9]+(?:\\.[0-9]+)?))?\\s*$",
+					"description": "Exactly three forms: single ref '<name>.<column>', ratio '<a>.<col> / <b>.<col>', or difference '<a>.<col> - <b>.<col>'. At most one binary operator; operands are refs or numeric literals (at least one ref — runtime-enforced). If a selection matches multiple rows, count-like columns sum and value-like columns error (single-row selection enforced). No free-form expressions."
+				},
+				"op": { "type": "string", "enum": [">=", "<=", ">", "<", "between"] },
+				"target": {
+					"oneOf": [
+						{ "type": "number" },
+						{
+							"type": "array",
+							"items": { "type": "number" },
+							"minItems": 2,
+							"maxItems": 2,
+							"description": "[lo, hi] — only valid with op 'between'."
+						}
+					],
+					"description": "The designed value — derive it from the same exported knob constants the hook uses so the assertion cannot drift from the mechanism."
+				},
+				"floor": {
+					"type": "number",
+					"description": "Optional STRONG bound — the minimum acceptable effect. Omitted → target doubles as the floor."
+				}
+			}
+		}
+	}
+}

package/lib/utils/json-evaluator.js

@@ -7,7 +7,7 @@ import { validateFunctionCall } from './function-registry.js';
 
 /**
  * Evaluate a value that might contain function calls
- * @param {any} value - The value to evaluate (could be object with functionName, array, or primitive)
+ * @param {unknown} value - The value to evaluate (could be object with functionName, array, or primitive)
  * @returns {string} - JavaScript code string
  */
 export function evaluateValue(value) {

package/lib/utils/utils.js

@@ -289,8 +289,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();
@@ -399,8 +399,9 @@ 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}`);