@ak--47/dungeon-master 1.8.0 → 1.8.2

package/lib/verify/funnel-engine.js

@@ -90,8 +90,10 @@
  *   trend-interval end and the data-pull range — fix-round C6).
  * @property {boolean} [graceperiod=true] - Enable the 2-second grace window
  *   on ordering checks. Disable only for tests that need strict ordering.
- * @property {boolean} [reentry=false] - When true, after completing all steps,
- *   reset to step 0 and continue scanning. Increments `completions`.
+ * @property {boolean} [reentry=false] - When true, restart after the inclusive
+ *   2-second completion grace. An event recording the ordered last step and
+ *   matching the ordered first step also anchors the next attempt immediately.
+ *   `graceperiod: false` disables the completion wait. Increments `completions`.
  *   Attempts ALSO restart when the conversion window expires (fix-round
  *   B2+C5): an incoming event past the window from step 0 finalizes the
  *   live attempt as a drop-off and processes against a fresh one — ARB
@@ -124,8 +126,8 @@
  *   fresh one processes the same event (funnel_query.cpp:1608-1613 — for
  *   GENERAL_WO_REPEAT termination checks ONLY history_is_past_conversion_
  *   window, not history_is_mutable; re-birth :1663-1680). Contrast
- *   `reentry: true` (GENERAL), which also restarts right after each
- *   completion/exclusion, permitting repeat conversions within one window.
+ *   `reentry: true` (GENERAL), which also restarts after completion grace or
+ *   exclusion, permitting repeat conversions within one window.
  *   Requires `countMode: 'totals'`; mutually exclusive with `reentry` and
  *   `sessionScoped`.
  * @property {boolean} [sessionScoped=false] - **@deprecated — verifier-only, NOT
@@ -185,7 +187,7 @@
 
 import { toMs } from '../hook-helpers/_internal.js';
 import { sessionOrdinals } from './sessionize.js';
-import { matchesWhere } from './coerce.js';
+import { coerceToBreakdownKey, matchesWhere } from './coerce.js';
 
 const OUT_OF_ORDER_MS = 2000;
 const DAY_MS = 86400 * 1000;
@@ -373,7 +375,7 @@ function emptyResult(trackStepProperties) {
  * @returns {{ result: FunnelResult, nextIdx: number, terminatedByExclusion: boolean, expiredByWindow: boolean }}
  */
 function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
-	const { windowCheck, graceperiod, trackStepProperties, anchorOk, isAnyOrder, prevAnchor, nextAnchor, expireOnWindow = false, woRepeat = false } = options;
+	const { windowCheck, graceperiod, trackStepProperties, anchorOk, isAnyOrder, prevAnchor, nextAnchor, expireOnWindow = false, woRepeat = false, restartSharedEdge = false } = options;
 	const numSteps = steps.length;
 	// Per-SLOT recorded candidates (history->steps): the latest match for
 	// anchors, the first eligible match for active any-order chunk members.
@@ -402,8 +404,9 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
 	let reached = -1;
 	let terminatedByExclusion = false;
 	let expiredByWindow = false;
+	let sharedEdgeCompleted = false;
 	let tailAnchorMs = 0; // terminating exclusion time, or last-step time on completion
-	let endIdx = -1;      // consumption boundary — frozen the moment the attempt is decided
+	let endIdx = -1;      // first event eligible for the next attempt
 	let i = startIdx;
 
 	// Does exclusion `ex` apply to gap g? afterStep/beforeStep bound the
@@ -586,8 +589,10 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
 
 		if (reached === numSteps - 1 && !terminatedByExclusion) {
 			tailAnchorMs = timeAtPos(numSteps - 1);
-			endIdx = i + 1;
-			// No break — the 2s tail may still kill the completion.
+			sharedEdgeCompleted = !woRepeat && numSteps > 1 && s === numSteps - 1
+				&& !isAnyOrder[0] && !isAnyOrder[numSteps - 1] && eventMatchesStep(ev, steps[0]);
+			endIdx = sharedEdgeCompleted && restartSharedEdge ? i : i + 1;
+			// Ordinary completions remain open for the 2s exclusion tail.
 		}
 		return true;
 	};
@@ -606,10 +611,10 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
 		// nextIdx = i, not i + 1. For GENERAL_WO_REPEAT (woRepeat) expiry is
 		// the ONLY termination — it fires even on completed/excluded attempts
 		// (:1611-1613). For GENERAL (the reentry loop) completion/exclusion
-		// keep their own restart below, so expiry only finalizes LIVE
-		// attempts (C5: failed-attempt windows).
+		// keep their own restart below; independent window expiry also
+		// finalizes a completion still inside its grace period.
 		if (expireOnWindow && reached >= 0
-			&& (woRepeat || (!terminatedByExclusion && reached !== numSteps - 1))
+			&& (woRepeat || !terminatedByExclusion)
 			&& !windowCheck(t, timeAtPos(0), ev, eventAtPos(0))
 		) {
 			expiredByWindow = true;
@@ -654,9 +659,15 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
 			// the event on their own: anchors need reached < slot; claimed
 			// any-order chunk members are first-match-sealed — so
 			// exclusions-only here matches ARB.)
-			if (!hasExclusions || !graceperiod || t > tailAnchorMs + OUT_OF_ORDER_MS) break;
-			for (let g = 0; g < numSteps - 1; g++) {
-				if (tryExclusionAtGap(g, ev, t)) break;
+			if (!graceperiod || t > tailAnchorMs + OUT_OF_ORDER_MS) {
+				endIdx = i;
+				break;
+			}
+			endIdx = i + 1;
+			if (hasExclusions) {
+				for (let g = 0; g < numSteps - 1; g++) {
+					if (tryExclusionAtGap(g, ev, t)) break;
+				}
 			}
 			continue;
 		}
@@ -693,6 +704,7 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
 				break;
 			}
 		}
+		if (sharedEdgeCompleted) break;
 	}
 
 	// Result surfaces the PATH (positions), not the slot table: position p was
@@ -772,6 +784,17 @@ function runOneAttempt(sorted, startIdx, steps, exclusionSteps, options) {
  * @returns {FunnelResult | FunnelResult[]}
  */
 export function evaluateFunnel(events, steps, options = {}) {
+	return evaluateFunnelWithContext(events, steps, options);
+}
+
+/**
+ * @param {Array<Object>} events
+ * @param {FunnelStep[]} steps
+ * @param {FunnelOptions} options
+ * @param {Map<Object, number>} [fullStreamOrdinals]
+ * @returns {FunnelResult | FunnelResult[]}
+ */
+function evaluateFunnelWithContext(events, steps, options, fullStreamOrdinals) {
 	if (options.countMode === 'sessions') {
 		// Mixpanel's funnel "count by Sessions" is an API rewrite, not an
 		// engine mode: count_type session REQUIRES window (session, 1) and
@@ -790,14 +813,14 @@ export function evaluateFunnel(events, steps, options = {}) {
 		if (typeof options.conversionWindowMs === 'number' || (cw != null && !(cw.unit === 'sessions' && cw.n === 1))) {
 			throw new Error("evaluateFunnel: cannot use countMode 'sessions' without conversion window = 1 session");
 		}
-		return evaluateFunnel(events, steps, {
+		return evaluateFunnelWithContext(events, steps, {
 			...options,
 			countMode: 'totals',
 			reentry: false,
 			woRepeat: true,
 			conversionWindowMs: undefined,
 			conversionWindow: { unit: 'sessions', n: 1 },
-		});
+		}, fullStreamOrdinals);
 	}
 	if (!Array.isArray(steps) || steps.length === 0) {
 		const empty = emptyResult(options.trackStepProperties);
@@ -871,7 +894,7 @@ export function evaluateFunnel(events, steps, options = {}) {
 		// the data-pull range (:402, :1408-1412) — the timeBucket wrapper's
 		// [start, stop + n×day) spill slice mirrors exactly that. Spec P1.6.1's
 		// dual per-step condition was a misreading; dropped per fix-round C6.
-		const ordinals = sessionOrdinals(sorted);
+		const ordinals = fullStreamOrdinals ?? sessionOrdinals(sorted);
 		windowCheck = (t, t0, ev, step0Ev) => {
 			const o = ordinals.get(ev);
 			const o0 = ordinals.get(step0Ev);
@@ -891,7 +914,7 @@ export function evaluateFunnel(events, steps, options = {}) {
 		}
 		const allResults = [];
 		for (const [sid, evs] of bySession) {
-			const sub = evaluateFunnel(evs, steps, { ...options, sessionScoped: false });
+			const sub = evaluateFunnelWithContext(evs, steps, { ...options, sessionScoped: false }, fullStreamOrdinals);
 			if (Array.isArray(sub)) {
 				for (const r of sub) { r.sessionId = sid; allResults.push(r); }
 			} else {
@@ -952,7 +975,7 @@ export function evaluateFunnel(events, steps, options = {}) {
 	const completedAttempts = [];
 	let idx = 0;
 	let lastResult = emptyResult(trackStepProperties);
-	const reentryOpts = { ...opts, expireOnWindow: true };
+	const reentryOpts = { ...opts, expireOnWindow: true, restartSharedEdge: true };
 	while (idx < sorted.length) {
 		const { result, nextIdx, terminatedByExclusion } = runOneAttempt(sorted, idx, normSteps, exclusionSteps, reentryOpts);
 		// Always advance — runOneAttempt returns nextIdx > idx when it processed an event.
@@ -990,15 +1013,24 @@ export function evaluateFunnel(events, steps, options = {}) {
  * `Map<propertyValue, FunnelResult>`.
  *
  * Each sub-funnel runs independently (a user CAN convert in one HPC value
- * group and drop off in another simultaneously).
+ * group and drop off in another simultaneously). Session windows derive
+ * ordinals from the full user stream before routing events to HPC buckets.
  *
- * Reference: `funnel_query.cpp` lines 749-784 (`aggregate_hash_get_key_cursor`).
+ * Analytics 717286d2: backend/arb/reader/queries/funnel_query.cpp:749
+ * processes each key from backend/libquery/aggregate.cpp:36,113. Ordinary
+ * HPC expands lists one level and accepts scalars. Both use value_to_string
+ * (backend/libquery/value/value.c:184), not typed breakdown/filter equality.
+ * Empty lists emit no visits; null/missing items use the "undefined" label.
+ * Duplicate labels share a history but retain cursor visits, which can
+ * advance repeated steps (funnel_query.cpp:1257; funnels/history.cpp:387).
  *
- * **Limitation (v1.5.0):** scalar HPC values only. Mixpanel's
- * `aggregate_hash_get_key_cursor` iterates *each value* of a list-valued
- * property, exploding into N sub-funnels per event. List-valued HPC keys are
- * not supported here — events with non-scalar `holdProperty` values will
- * stringify and bucket incorrectly.
+ * Compatibility: all-scalar streams retain raw keys and omit null/missing
+ * values. List-bearing streams use string labels for all routed values.
+ * This property-name API does not expose the separate explicit-list mode,
+ * which rejects non-lists (aggregate.cpp:126). Events and their copy-data
+ * properties remain unchanged; only the routing key is normalized.
+ * The shared label helper does not reproduce ARB's numeric %.16g fallback,
+ * structured-value serialization/truncation, or aggregate cardinality cap.
  *
  * @param {Array<Object>} events
  * @param {FunnelStep[]} steps
@@ -1017,6 +1049,14 @@ export function evaluateFunnelHPC(events, steps, holdProperty, options = {}) {
 		throw new Error('evaluateFunnelHPC: an anyOrder block cannot be the first funnel step');
 	}
 	const step0Name = flat[0].event;
+	const fullStreamOrdinals = options.countMode === 'sessions' || options.conversionWindow?.unit === 'sessions'
+		? sessionOrdinals((events || []).filter(ev => ev && typeof ev.event === 'string'))
+		: undefined;
+	const hasListValues = (events || []).some(ev => ev && typeof ev.event === 'string' && Array.isArray(ev[holdProperty]));
+	const heldValues = (value) => {
+		if (!hasListValues) return value == null ? [] : [value];
+		return (Array.isArray(value) ? value : [value]).map(coerceToBreakdownKey);
+	};
 
 	// Bucket events by HPC value. The step-0 events define the universe of
 	// HPC values for this user; later events only populate buckets whose
@@ -1026,31 +1066,31 @@ export function evaluateFunnelHPC(events, steps, holdProperty, options = {}) {
 		if (!ev || typeof ev.event !== 'string') continue;
 		// Step-0 events seed the bucket on their own value.
 		if (ev.event === step0Name) {
-			const v = ev[holdProperty];
-			if (v === undefined || v === null) continue;
-			if (!valueBuckets.has(v)) valueBuckets.set(v, []);
-			valueBuckets.get(v).push(ev);
+			for (const value of heldValues(ev[holdProperty])) {
+				if (!valueBuckets.has(value)) valueBuckets.set(value, []);
+				valueBuckets.get(value).push(ev);
+			}
 		}
 	}
 	// Now route every event with a known HPC value into its bucket.
 	for (const ev of events || []) {
 		if (!ev || typeof ev.event !== 'string' || ev.event === step0Name) continue;
-		const v = ev[holdProperty];
-		if (v === undefined || v === null) continue;
-		if (valueBuckets.has(v)) valueBuckets.get(v).push(ev);
+		for (const value of heldValues(ev[holdProperty])) {
+			if (valueBuckets.has(value)) valueBuckets.get(value).push(ev);
+		}
 	}
 
 	const out = new Map();
 	for (const [v, evs] of valueBuckets) {
-		out.set(v, evaluateFunnel(evs, steps, options));
+		out.set(v, evaluateFunnelWithContext(evs, steps, options, fullStreamOrdinals));
 	}
 	return out;
 }
 
 /**
- * Resolve the property snapshot for a given segment mode against a result's
- * `stepProperties`. Use to mimic Mixpanel's FIRST_TOUCH / LAST_TOUCH / STEP
- * funnel segment modes.
+ * Merge reached `stepProperties` in recorded path order for FIRST_TOUCH or
+ * LAST_TOUCH. Undefined never replaces a defined value; null never replaces
+ * a non-null defined value. STEP returns its selected snapshot unchanged.
  *
  * @param {FunnelResult} result
  * @param {'first'|'last' | { step: number }} mode
@@ -1058,8 +1098,21 @@ export function evaluateFunnelHPC(events, steps, holdProperty, options = {}) {
  */
 export function resolveFunnelSegment(result, mode) {
 	if (!result || !Array.isArray(result.stepProperties) || !result.stepProperties.length) return undefined;
-	if (mode === 'first') return result.stepProperties[0];
-	if (mode === 'last')  return result.stepProperties[result.reached >= 0 ? result.reached : result.stepProperties.length - 1];
+	if (mode === 'first' || mode === 'last') {
+		const merged = {};
+		const snapshots = result.stepProperties.slice(0, result.reached + 1);
+		if (mode === 'first') snapshots.reverse();
+		for (const snapshot of snapshots) {
+			for (const [key, value] of Object.entries(snapshot || {})) {
+				const current = Object.prototype.hasOwnProperty.call(merged, key) ? merged[key] : undefined;
+				if (current === undefined || (current === null && value !== undefined)
+					|| (value !== undefined && value !== null)) {
+					Object.defineProperty(merged, key, { value, enumerable: true, configurable: true, writable: true });
+				}
+			}
+		}
+		return merged;
+	}
 	if (mode && typeof mode === 'object' && typeof mode.step === 'number') {
 		return result.stepProperties[mode.step];
 	}

package/lib/verify/identity.js

@@ -1,15 +1,13 @@
 /**
- * Identity resolution for verifier — builds a device→user map from profiles
- * and resolves a canonical user id per event. Mirrors Mixpanel's ID merge
- * semantics: pre-auth events stamped with `device_id` and post-auth events
- * stamped with `user_id` belong to the same canonical identity.
+ * Identity resolution for verifier. Automatic links come from emitted
+ * both-ID events; profile pools are only an explicit caller override.
  *
- * Reference: `mixpanel/analytics` — identity merge / profiles `device_ids`
- * inversion. We invert each profile's `device_ids` array into a flat
- * `Map<device_id, canonical_user_id>` so query-time event grouping resolves
- * pre-auth touches alongside post-auth events.
+ * Reference: analytics identity-manager v3 lookup_and_update_handler.go
+ * and identity/device_and_user_records.go at 717286d2d3ed03e9e3f9cb4346e4c6b2e561fb9a.
  */
 
+const emittedIdentityMap = Symbol('emittedIdentityMap');
+
 /**
  * Build a `Map<device_id, canonical_user_id>` by inverting each profile's
  * device-pool array. Reads `device_ids` first, falling back to the legacy
@@ -41,12 +39,36 @@ export function buildIdentityMap(profiles) {
 	return map;
 }
 
+/**
+ * Build automatic device-to-user links from the full emitted stream.
+ * Event names do not gate linking. The first valid pair for a device wins;
+ * v3 does not reassign an already-linked device to a conflicting user.
+ * User IDs with the reserved $device: prefix cannot establish a link.
+ *
+ * @param {Array<Object>} events
+ * @returns {Map<string, string>}
+ */
+export function buildEventIdentityMap(events) {
+	const map = new Map();
+	Object.defineProperty(map, emittedIdentityMap, { value: true });
+	if (!Array.isArray(events)) return map;
+	for (const event of events) {
+		const deviceId = event?.device_id;
+		const userId = event?.user_id;
+		if (typeof deviceId !== 'string' || !deviceId.trim()
+			|| typeof userId !== 'string' || !userId.trim()
+			|| userId.startsWith('$device:') || map.has(deviceId)) continue;
+		map.set(deviceId, userId);
+	}
+	return map;
+}
+
 /**
  * Resolve the canonical user id for an event. Lookup order:
  *   1. `event.distinct_id` — Mixpanel's canonical post-merge identifier. When
  *      a downstream pipeline has already stitched the cluster, this is the
  *      ground truth; never override it.
- *   2. `identityMap.get(event.device_id)` — device→user merge from profile inversion.
+ *   2. `identityMap.get(event.device_id)` — emitted link or explicit override.
  *   3. `event.user_id` — already authed (pre-merge analog of distinct_id).
  *   4. `event.device_id` — anonymous fallback.
  *
@@ -70,6 +92,7 @@ export function buildIdentityMap(profiles) {
 export function resolveUserId(event, identityMap) {
 	if (!event) return undefined;
 	if (event.distinct_id) return event.distinct_id;
+	if (event.user_id && identityMap && Object.getOwnPropertyDescriptor(identityMap, emittedIdentityMap)) return event.user_id;
 	if (identityMap && event.device_id) {
 		const merged = identityMap.get(event.device_id);
 		if (merged) return merged;

package/lib/verify/story-runner.js

@@ -20,9 +20,9 @@
  * neutral. For 'between' the wanted side is where the band's midpoint sits
  * relative to the neutral point.
  *
- * Cohort size per named selection: sum of `user_count` over the selected rows
- * when any row carries one, else the row count. The SMALLEST selection is
- * compared against `minCohort`.
+ * Cohort evidence per selection is an independent-user lower bound: sum only
+ * proven disjoint bins within a period, then take the largest period. Other
+ * user counts use the largest row. Missing evidence caps passes at WEAK.
  */
 
 import { emulateBreakdown } from './emulate-breakdown.js';
@@ -166,11 +166,59 @@ function resolveRef(ref, selected) {
 	return sum;
 }
 
-function cohortOf(rows) {
-	if (rows.some(r => typeof r.user_count === 'number')) {
-		return rows.reduce((s, r) => s + (typeof r.user_count === 'number' ? r.user_count : 0), 0);
+function cohortOf(rows, breakdown, sourceRows) {
+	if (!Array.isArray(rows)) return null;
+	let evidenceRows = (rows || []).filter(row => row && !row._empty);
+	if (!evidenceRows.length) return null;
+	const isCount = value => Number.isSafeInteger(value) && value >= 0;
+	const hasPeriod = row => typeof row.period === 'string' && row.period.length > 0;
+	let column = 'user_count';
+	let binColumns = [];
+	if (breakdown.type === 'funnelFrequency') {
+		if (breakdown.countMode !== undefined && breakdown.countMode !== 'uniques') return null;
+		const periodRequired = breakdown.timeBucket !== undefined || evidenceRows.some(row => row.period !== undefined);
+		if (evidenceRows.some(row => !isCount(row.step_index) || !isCount(row.breakdown_freq)
+			|| (periodRequired && !hasPeriod(row)))) return null;
+		const binKey = row => JSON.stringify([row.period, row.breakdown_freq]);
+		const selectedBins = new Set(evidenceRows.map(binKey));
+		evidenceRows = (sourceRows || []).filter(row => row && !row._empty && row.step_index === 0
+			&& isCount(row.breakdown_freq) && (row.period === undefined || hasPeriod(row))
+			&& selectedBins.has(binKey(row)));
+		if (new Set(evidenceRows.map(binKey)).size !== selectedBins.size) return null;
+		column = 'conversions';
+		binColumns = ['breakdown_freq'];
+	} else if (breakdown.type === 'eventBreakdown') {
+		column = 'total_users';
+	} else if (breakdown.type === 'uniques') {
+		if (breakdown.countType !== undefined && breakdown.countType !== 'unique') return null;
+		column = 'uniques';
+	} else if (breakdown.type === 'retention') {
+		column = 'cohort_size';
+	} else if (breakdown.type === 'frequencyByFrequency') {
+		binColumns = ['metric_freq', 'breakdown_freq'];
+	} else if (breakdown.type === 'aggregatePerUser') {
+		binColumns = ['breakdown_freq'];
 	}
-	return rows.length;
+	if (evidenceRows.some(row => !isCount(row[column]))) return null;
+	const largestRow = evidenceRows.reduce((largest, row) => Math.max(largest, row[column]), 0);
+	const periodRequired = breakdown.timeBucket !== undefined || evidenceRows.some(row => row.period !== undefined);
+	if (!binColumns.length || evidenceRows.some(row => binColumns.some(bin => !isCount(row[bin]))
+		|| (periodRequired && !hasPeriod(row)))) return largestRow;
+	const periods = new Map();
+	for (const row of evidenceRows) {
+		if (!periods.has(row.period)) periods.set(row.period, new Map());
+		const bins = periods.get(row.period);
+		const key = JSON.stringify(binColumns.map(bin => row[bin]));
+		bins.set(key, Math.max(bins.get(key) || 0, row[column]));
+	}
+	let largestPeriod = 0;
+	for (const bins of periods.values()) {
+		let total = 0;
+		for (const count of bins.values()) total += count;
+		if (!Number.isSafeInteger(total)) return largestRow;
+		largestPeriod = Math.max(largestPeriod, total);
+	}
+	return largestPeriod;
 }
 
 // ── verdicts ────────────────────────────────────────────────────────────────
@@ -243,40 +291,55 @@ const fmt = (n) => (typeof n === 'number' && Number.isFinite(n)) ? (Math.abs(n)
  */
 export function evaluateAssertion(rows, assertion, ctx) {
 	try {
+		const minCohort = assertion.minCohort;
+		let result, selected, cohorts;
 		if (typeof assertion.assert === 'function') {
+			if (typeof minCohort === 'number') {
+				selected = assertion.select === undefined ? { all: rows } : selectRows(rows, assertion.select);
+				cohorts = Object.values(selected).map(selection => cohortOf(selection, assertion.breakdown, rows));
+			}
 			/** @type {{ pass?: boolean, detail?: string, verdict?: import('../../types').StoryVerdict }} */
 			const res = assertion.assert(rows, ctx) || {};
 			if (res.verdict && VERDICT_RANK[res.verdict] !== undefined) {
-				return { verdict: res.verdict, observed: null, detail: res.detail || 'custom assert' };
+				result = { verdict: res.verdict, observed: null, detail: res.detail || 'custom assert' };
+			} else {
+				result = res.pass
+					? { verdict: 'STRONG', observed: null, detail: res.detail || 'custom assert passed' }
+					: { verdict: 'NONE', observed: null, detail: res.detail || 'custom assert failed' };
 			}
-			return res.pass
-				? { verdict: 'STRONG', observed: null, detail: res.detail || 'custom assert passed' }
-				: { verdict: 'NONE', observed: null, detail: res.detail || 'custom assert failed' };
-		}
-		const parsed = parseMetric(assertion.expect.metric);
-		const selected = selectRows(rows, assertion.select);
-		const left = resolveRef(parsed.left, selected);
-		let observed, neutral;
-		if (parsed.kind === 'single') {
-			observed = left; neutral = null;
 		} else {
-			const right = resolveRef(parsed.right, selected);
-			if (parsed.kind === 'ratio') {
-				if (right === 0) throw new Error('ratio denominator is 0');
-				observed = left / right; neutral = 1;
+			const parsed = parseMetric(assertion.expect.metric);
+			selected = selectRows(rows, assertion.select);
+			const left = resolveRef(parsed.left, selected);
+			let observed, neutral;
+			if (parsed.kind === 'single') {
+				observed = left; neutral = null;
 			} else {
-				observed = left - right; neutral = 0;
+				const right = resolveRef(parsed.right, selected);
+				if (parsed.kind === 'ratio') {
+					if (right === 0) throw new Error('ratio denominator is 0');
+					observed = left / right; neutral = 1;
+				} else {
+					observed = left - right; neutral = 0;
+				}
 			}
+			const { verdict, detail } = verdictFor(observed, assertion.expect, neutral);
+			result = { verdict, observed, detail };
 		}
-		let { verdict, detail } = verdictFor(observed, assertion.expect, neutral);
-		if (typeof assertion.minCohort === 'number' && VERDICT_RANK[verdict] > VERDICT_RANK.WEAK) {
-			const smallest = Math.min(...Object.values(selected).map(cohortOf));
-			if (smallest < assertion.minCohort) {
-				verdict = 'WEAK';
-				detail += ` — capped: smallest cohort ${smallest} < minCohort ${assertion.minCohort}`;
+		if (typeof minCohort === 'number' && VERDICT_RANK[result.verdict] > VERDICT_RANK.WEAK) {
+			cohorts ??= Object.values(selected).map(selection => cohortOf(selection, assertion.breakdown, rows));
+			if (!cohorts.length || cohorts.some(cohort => cohort === null)) {
+				result.verdict = 'WEAK';
+				result.detail += ` - capped: insufficient evidence for minCohort ${minCohort}; independent-user denominator unavailable`;
+			} else {
+				const smallest = Math.min(...cohorts);
+				if (smallest < minCohort) {
+					result.verdict = 'WEAK';
+					result.detail += ` - capped: insufficient evidence; smallest independent-user lower bound ${smallest} < minCohort ${minCohort}`;
+				}
 			}
 		}
-		return { verdict, observed, detail };
+		return result;
 	} catch (err) {
 		return { verdict: 'NONE', observed: null, detail: `error: ${err.message}` };
 	}

package/lib/verify/verify-dungeon.js

@@ -21,6 +21,7 @@
 
 import DUNGEON_MASTER from '../../index.js';
 import { emulateBreakdown } from './emulate-breakdown.js';
+import { buildEventIdentityMap } from './identity.js';
 import { validateSchema } from './schema-validator.js';
 
 /**
@@ -83,7 +84,7 @@ export function applyFunnelDefaults(breakdownArgs, funnels, profiles) {
 			// is the author choosing a window — injecting conversionWindowMs on top
 			// would trip evaluateFunnel's mutual-exclusion throw. Only inject when
 			// NEITHER window form is present.
-			if (args.conversionWindowMs === undefined && args.conversionWindow === undefined && Number.isFinite(matched.conversionWindowDays)) {
+			if (args.countMode !== 'sessions' && args.conversionWindowMs === undefined && args.conversionWindow === undefined && Number.isFinite(matched.conversionWindowDays)) {
 				args.conversionWindowMs = matched.conversionWindowDays * 86400000;
 			}
 			if (args.funnelOrder === undefined && matched.order) {
@@ -137,6 +138,7 @@ export async function verifyDungeon(config, checks, overrides) {
 	}
 	const events = Array.isArray(result.eventData) ? result.eventData : Array.from(result.eventData);
 	const profiles = Array.isArray(result.userProfilesData) ? result.userProfilesData : Array.from(result.userProfilesData);
+	const identityMap = buildEventIdentityMap(events);
 	// v1.6.2: schema-check against the config the run actually used. `config` may be a
 	// PATH STRING (no fields at all → every property reads as unexpected), and even for
 	// an object input a v1.5.1 dungeon keeps `hasAndroidDevices` / `hasBrowser` under
@@ -155,6 +157,7 @@ export async function verifyDungeon(config, checks, overrides) {
 	for (const check of checks) {
 		try {
 			const breakdownArgs = applyFunnelDefaults(check.breakdown, validatedFunnels, profiles);
+			if (breakdownArgs.identityMap === undefined) breakdownArgs.identityMap = identityMap;
 			const rows = emulateBreakdown(events, breakdownArgs);
 			const verdict = check.assert(rows, ctx);
 			results.push({ name: check.name, pass: !!verdict.pass, detail: verdict.detail, rows });

package/package.json

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

package/scripts/verify-stories.mjs

@@ -38,8 +38,8 @@ import { parse as parseCsv } from 'csv-parse';
 import generate from '../index.js';
 import { extractComments } from '../lib/core/extract-comments.js';
 import { validateDungeonConfig } from '../lib/core/config-validator.js';
+import { buildEventIdentityMap } from '../lib/verify/identity.js';
 import {
-	buildIdentityMap,
 	VERDICT_RANK,
 	validateStories,
 	validateSchema,
@@ -149,7 +149,7 @@ if (inMemory) {
 		? await evaluateStories(stories, events, {
 			profiles,
 			funnels: Array.isArray(validated.funnels) ? validated.funnels : [],
-			identityMap: buildIdentityMap(profiles),
+			identityMap: buildEventIdentityMap(events),
 			warehouseRows,
 			warehouseSpecs,
 			datasetStart: validated.datasetStart,
@@ -187,7 +187,7 @@ if (inMemory) {
 	// here and use the RETURN value — as of v1.6.2 validateDungeonConfig does not
 	// enrich the object you hand it.
 	const validated = validateDungeonConfig({ ...config, token: '' });
-	const identityMap = buildIdentityMap(profiles);
+	const identityMap = buildEventIdentityMap(events);
 	schemaPass = !!validateSchema(events, validated)?.pass;
 	const warehouseSpecs = Object.fromEntries((validated.warehouseMetrics || []).map((spec) => [spec.name, spec]));
 	const warehouseManifest = loadWarehouseManifest(prefixPath);

package/types.d.ts

@@ -2683,10 +2683,10 @@ declare module '@ak--47/dungeon-master/hook-helpers' {
     export function injectOnNewDays(events: EventSchema[], eventName: string, targetDays: number, options?: { timeRange?: 'active'; overrides?: Partial<EventSchema> }): EventSchema[];
     /** v1.6.0 — carve a dormant window (drop value moments, or all events with `dropAll`) then append a resurrection burst cloned from the surviving value-moment template. Returns a NEW array. */
     export function applyLifecycleWave(events: EventSchema[], uid: string, opts: { dormantFromDay: number; dormantDays: number; valueMomentEvent: string; resurrectBurst?: number; dropAll?: boolean }): EventSchema[];
-    /** v1.6.0 — inject an ordered event path after each anchor for a deterministic `share` of users (hash-gated). Augments in place; engine auto-sort handles ordering. */
+    /** v1.6.0 — append an ordered path after the FIRST chronological anchor for a deterministic `share` of users. Original traffic is untouched and can interrupt the immediate branch; share is an injection gate, not a measured Flows share. */
     export function applyPathBias(events: EventSchema[], uid: string, opts: { anchor: string; path: string[]; share: number; gapSeconds?: [number, number] }): EventSchema[];
-    /** v1.6.0 — rewrite the user's timestamps into deterministic session clusters (n/week, m events, bounded span) that survive query-time re-derivation. */
-    export function applySessionShape(events: EventSchema[], uid: string, opts: { sessionsPerWeek: number; eventsPerSession: number; sessionMinutes: number }): EventSchema[];
+    /** Retiming only; preserves every record. Both bounds omitted retain legacy full-UTC-day placement, including nonthrowing overfull requests whose clusters may merge. Optional inclusive bounds accept ISO, unix seconds or milliseconds (hook meta directly); an omitted side uses its original UTC day edge. The helper cannot infer datasetEnd. Explicit-bound mode throws RangeError before mutation for invalid bounds or insufficient per-week 30-minute-session capacity. Pass known metadata bounds to prevent later engine clipping. */
+    export function applySessionShape(events: EventSchema[], uid: string, opts: { sessionsPerWeek: number; eventsPerSession: number; sessionMinutes: number; datasetStart?: string | number; datasetEnd?: string | number }): EventSchema[];
 }
 
 declare module '@ak--47/dungeon-master/hook-patterns' {
@@ -2926,6 +2926,9 @@ declare module '@ak--47/dungeon-master/verify' {
          */
         conversionWindow?: { unit: 'sessions'; n: number };
         graceperiod?: boolean;
+        /** Defaults to false, including totals. Restart after inclusive 2s completion grace;
+         * ordered shared last/first edges restart on the completion event itself.
+         * graceperiod=false disables the wait; window expiry can restart earlier. */
         reentry?: boolean;
         exclusionSteps?: ExclusionStep[];
         trackStepProperties?: boolean | string[];
@@ -2958,9 +2961,10 @@ declare module '@ak--47/dungeon-master/verify' {
     }
     /** Evaluate a funnel against a user's events. Returns FunnelResult or array (totals mode). */
     export function evaluateFunnel(events: Array<Record<string, unknown>>, steps: FunnelStep[], options?: FunnelOptions): FunnelResult | FunnelResult[];
-    /** Hold Property Constant — runs parallel sub-funnels per unique value of `holdProperty`. */
+    /** Hold Property Constant: parallel sub-funnels per held value; session ordinals use the full user stream. */
     export function evaluateFunnelHPC(events: Array<Record<string, unknown>>, steps: FunnelStep[], holdProperty: string, options?: FunnelOptions): Map<string | number, FunnelResult | FunnelResult[]>;
-    /** Pick a property snapshot from a FunnelResult for the given segment mode. */
+    /** Merge reached snapshots in path order for first/last touch. Undefined and null preserve
+     * defined non-null fallback values. Explicit step selection returns its snapshot unchanged. */
     export function resolveFunnelSegment(result: FunnelResult, mode: 'first' | 'last' | { step: number }): Record<string, unknown> | undefined;
     /** Normalize a FunnelStep to the `{ event, where? }` canonical shape. */
     export function normalizeStep(step: FunnelStep): { event: string; where?: { prop: string; op: string; value: unknown } };