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

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
@@ -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,7 +1013,8 @@ 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`).
  *
@@ -1017,6 +1041,9 @@ 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;
 
 	// Bucket events by HPC value. The step-0 events define the universe of
 	// HPC values for this user; later events only populate buckets whose
@@ -1042,15 +1069,15 @@ export function evaluateFunnelHPC(events, steps, holdProperty, options = {}) {
 
 	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 +1085,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/package.json

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

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 } };