@ak--47/dungeon-master 1.4.4 → 1.5.0

package/lib/verify/verify-dungeon.js

@@ -30,6 +30,28 @@ import { validateSchema } from './schema-validator.js';
  * @property {(rows: Array<Object>, ctx: { events: Array<Object>, profiles: Array<Object> }) => { pass: boolean, detail?: string }} assert
  */
 
+/**
+ * Try to find the dungeon funnel whose `sequence` matches the breakdown's funnel
+ * steps. Used to auto-apply v1.5 `conversionWindowDays` + `order`-mode dispatch
+ * without forcing every check author to thread these args by hand.
+ * @param {Array<Object>} funnels
+ * @param {string[]} steps
+ * @returns {Object | null}
+ */
+function findMatchingFunnel(funnels, steps) {
+	if (!Array.isArray(funnels) || !Array.isArray(steps) || !steps.length) return null;
+	for (const f of funnels) {
+		if (!f || !Array.isArray(f.sequence)) continue;
+		if (f.sequence.length !== steps.length) continue;
+		let same = true;
+		for (let i = 0; i < steps.length; i++) {
+			if (f.sequence[i] !== steps[i]) { same = false; break; }
+		}
+		if (same) return f;
+	}
+	return null;
+}
+
 /**
  * @param {Object} config - Dungeon config (or path; passed straight to DUNGEON_MASTER).
  * @param {VerifyCheck[]} checks
@@ -44,12 +66,48 @@ export async function verifyDungeon(config, checks) {
 	const schemaReport = validateSchema(events, config);
 	const ctx = { events, profiles, schemaReport };
 	const results = [];
+	// `validateDungeonConfig` mutates funnels in place — by the time we read here,
+	// `conversionWindowDays` is populated and `order` is the validated value.
+	const validatedFunnels = (config && Array.isArray(config.funnels)) ? config.funnels : [];
 	for (const check of checks) {
 		try {
 			const breakdownArgs = { ...check.breakdown };
 			if (breakdownArgs.type === 'timeToConvert' && !breakdownArgs.profiles) {
 				breakdownArgs.profiles = profiles;
 			}
+			// v1.5: auto-apply funnel-level config when the check targets a funnel.
+			if (breakdownArgs.type === 'funnelFrequency' || breakdownArgs.type === 'timeToConvert') {
+				const targetSteps = breakdownArgs.steps
+					|| (breakdownArgs.fromEvent && breakdownArgs.toEvent
+						? [breakdownArgs.fromEvent, breakdownArgs.toEvent]
+						: null);
+				const matched = findMatchingFunnel(validatedFunnels, targetSteps);
+				if (matched) {
+					if (breakdownArgs.conversionWindowMs === undefined && Number.isFinite(matched.conversionWindowDays)) {
+						breakdownArgs.conversionWindowMs = matched.conversionWindowDays * 86400000;
+					}
+					if (breakdownArgs.funnelOrder === undefined && matched.order) {
+						breakdownArgs.funnelOrder = matched.order;
+					}
+					// v1.5.0: thread Funnel-level extension hints through to the verifier.
+					if (breakdownArgs.reentry === undefined && matched.reentry !== undefined) {
+						breakdownArgs.reentry = matched.reentry;
+					}
+					if (breakdownArgs.exclusionSteps === undefined && Array.isArray(matched.exclusionEvents) && matched.exclusionEvents.length) {
+						breakdownArgs.exclusionSteps = matched.exclusionEvents.map(name => ({ event: name }));
+					}
+					// stepFilters: Record<number, { prop, op, value }> → mutate steps to attach where-clause.
+					if (matched.stepFilters && breakdownArgs.steps && Array.isArray(breakdownArgs.steps)) {
+						breakdownArgs.steps = breakdownArgs.steps.map((s, i) => {
+							const filter = matched.stepFilters[i];
+							if (!filter) return s;
+							const stepObj = typeof s === 'string' ? { event: s } : { ...s };
+							if (!stepObj.where) stepObj.where = filter;
+							return stepObj;
+						});
+					}
+				}
+			}
 			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.4.4",
+	"version": "1.5.0",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -23,7 +23,9 @@
 		"dungeons/",
 		"!dungeons/customers/",
 		"!dungeons/user/",
+		"!dungeons/capstone/",
 		"scripts/",
+		".claude/skills/",
 		"package.json",
 		"README.md",
 		"CHANGELOG.md",
@@ -41,7 +43,7 @@
 		"test:coverage": "NODE_ENV=test vitest run --coverage",
 		"typecheck": "tsc --noEmit",
 		"dev": "nodemon scratch.mjs --ignore ./data/*",
-		"prune": "rm -f ./data/* && rm -f ./tmp/* && rm -f vscode-profile-*",
+		"prune": "find ./data -mindepth 1 -not -name .gitkeep -delete && find ./tmp -mindepth 1 -not -name .gitkeep -delete && rm -f vscode-profile-*",
 		"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",

package/types.d.ts

@@ -28,6 +28,11 @@ export interface Dungeon {
     /**
      * Number of days the dataset spans. Default: 30.
      *
+     * Safe range: `[14, 365]`. Below 14 → strict-bar engine-validation metrics use
+     * 14-day windows; results are noisy. Above 365 → memory cost grows linearly.
+     * Validator emits a warning below 14; does not clamp (because the window may have
+     * been pinned via `datasetStart`/`datasetEnd` upstream).
+     *
      * Three resolution modes:
      * 1. **`numDays` alone (no datasetStart/End):** Window = `[today - numDays, today]`.
      *    Simplest API for ad-hoc dungeons. NOT deterministic across runs (today changes).
@@ -58,7 +63,14 @@ export interface Dungeon {
     numEvents?: number;
     /** Number of unique users to generate. */
     numUsers?: number;
-    /** Average events per user per active day. The canonical event-volume primitive — born-late users get this rate × their remaining window, so per-day density stays constant. If both this and numEvents are set, this wins. */
+    /**
+     * Average events per user per active day. The canonical event-volume primitive —
+     * born-late users get this rate × their remaining window, so per-day density stays
+     * constant. If both this and numEvents are set, this wins.
+     *
+     * Safe range: `[0.1, 50]`. Above 50 → unrealistic load + memory cost; the v1.5
+     * validator strict-clamps to 50 with a warning.
+     */
     avgEventsPerUserPerDay?: number;
     /** Output format for files written to disk. */
     format?: "csv" | "json" | "parquet" | string;
@@ -119,6 +131,24 @@ export interface Dungeon {
     gzip?: boolean;
     /** If true, prints progress to stdout during generation. */
     verbose?: boolean;
+    /**
+     * Optional callback that receives periodic progress updates during generation,
+     * import, and pipeline step transitions. Fire-and-forget: the callback is never
+     * awaited. If it throws 3 times, it is silently disabled for the rest of the job.
+     *
+     * The `update` argument is a discriminated union on `phase`:
+     * - `"generation"` — user/event counts, EPS, memory, percent complete
+     * - `"import"` — record type, processed/total counts, EPS, bytes
+     * - `"step"` — pipeline step name with start/complete status and duration
+     *
+     * @example
+     * onProgress: (update) => {
+     *   if (update.phase === 'generation') ws.send(JSON.stringify(update));
+     * }
+     */
+    onProgress?: (update: ProgressUpdate) => void;
+    /** Minimum interval (ms) between progress callback invocations. Default: 500. Only throttles `generation` and `import` phases; `step` updates always fire immediately. */
+    progressInterval?: number;
     /**
      * @deprecated Prefer `avgDevicePerUser`. `true` is now an alias for `avgDevicePerUser: 1`
      * (single sticky device per user, every event stamped with that `device_id`). `false`
@@ -224,12 +254,81 @@ export interface Dungeon {
     // ── Distribution Controls ──
     // These three knobs are normally set by the `macro` preset (default "flat").
     // Setting them on the dungeon config directly overrides the preset's value.
-    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default (from macro: "flat"): 50 */
+    /**
+     * Percentage of users whose account creation falls within the dataset window (vs. pre-existing).
+     *
+     * Safe range: `[0, 100]` (sanity-clamped). Recommended `[0, 60]`. **v1.5 strict-clamp:**
+     * when `macro` is set to a named preset AND the user explicitly sets this field, it is
+     * clamped to the preset's default born% (flat=12, steady=12, growth=30, viral=55,
+     * decline=5) to preserve the macro's characteristic shape. Users who need higher born%
+     * should switch macros (flat→growth, growth→viral). When `macro` is not set, no clamp
+     * fires (legacy backward-compat).
+     */
     percentUsersBornInDataset?: number;
-    /** Bias for birth dates of users born in dataset. -1..1; negative = early skew, positive = recent skew, 0 = uniform. Default (from macro: "flat"): 0 */
+    /**
+     * Bias for birth dates of users born in dataset. -1..1; negative = early skew,
+     * positive = recent skew, 0 = uniform.
+     *
+     * Safe range: `[-0.5, 0.5]`. **v1.5 strict-clamp:** values outside `[-0.5, 0.5]` are
+     * clamped to the nearest bound (above 0.5 = unusable right-skew; below -0.5 = unusable
+     * left-skew). Compound clamp: when explicit `percentUsersBornInDataset > 60` AND
+     * explicit `bornRecentBias > 0.4`, bias is clamped to 0.3 to prevent right-edge
+     * cumulative-acquisition explosion. Macro presets (e.g., viral=0.6) are exempt.
+     */
     bornRecentBias?: number;
     /** How pre-existing users' first event time is placed. "pinned" stacks them all at FIXED_BEGIN; "uniform" spreads across [FIXED_BEGIN-30d, FIXED_BEGIN]. Default (from macro: "flat"): "uniform" */
     preExistingSpread?: "pinned" | "uniform";
+
+    // ── v1.5 Distinct-Day + Mixpanel Cap Primitives ──
+    /**
+     * Mean number of distinct UTC days each user fires events on. CONCENTRATOR semantic —
+     * total event count is preserved (still `avgEventsPerUserPerDay × userActiveDays`),
+     * but events cluster onto fewer days. Per-user count drawn from
+     * `normal(mean=avgActiveDaysPerUser, sd=mean/3)`, clamped to `[1, userActiveDays]`.
+     *
+     * Default: undefined (legacy — every window-day potentially active, no concentration).
+     *
+     * Per-active-day rate inflates: `(avgEventsPerUserPerDay × numDays) / avgActiveDaysPerUser`.
+     * Validator warns when implied per-active-day rate > 50.
+     *
+     * Day picking: weighted-without-replacement from candidate UTC days using
+     * `soup.dayOfWeekWeights`, so weekly rhythm is preserved at the cohort level.
+     *
+     * **Incompatibility with `engagementDecay`:** decay drops events from late picked days,
+     * eroding the effective active-day count below the configured target. Use one or the
+     * other; if you need both, write decay logic in an `everything` hook scoped to specific
+     * cohorts. See HOOKS.md §2.5.
+     *
+     * Safe range: `[1, numDays * 0.5]`. Above 50% of `numDays` defeats the concentrator
+     * purpose; the v1.5 validator strict-clamps to `floor(numDays * 0.5)` with a warning.
+     */
+    avgActiveDaysPerUser?: number;
+    /**
+     * Maximum number of UTM-stamped events per user. Matches Mixpanel's `TOUCHPOINTS_LIMIT`
+     * (`backend/libquery/properties_over_time/attributed_value_reader.cpp` line 16).
+     *
+     * Default: 10.
+     *
+     * When `hasCampaigns: true` and a user has more eligible events than the cap, the
+     * engine takes a uniform-random sample of size `cap` from the eligible pool (seeded,
+     * deterministic), sorts the sample chronologically, then stamps UTMs. Sampling
+     * across the user's lifetime — NOT first-N-chronological — preserves realistic
+     * touch distribution and lets Mixpanel's last-10-window report give meaningful
+     * first/last-touch attribution.
+     *
+     * Set to `Infinity` to disable the cap (legacy behavior, ~25% of eligible events stamped).
+     */
+    maxTouchpointsPerUser?: number;
+    /**
+     * If true (default), the engine sorts each user's events ascending by `time` after
+     * the `everything` hook returns, before the events are pushed to storage. Defends
+     * against the most common new footgun: hooks that `push()` cloned events with arbitrary
+     * timestamps and break the greedy funnel engine's chronological-order requirement.
+     *
+     * Set to `false` to preserve the hook's order (advanced — hook must guarantee its own
+     * ordering for downstream Mixpanel-aligned counting).
+     */
+    autoSortAfterEverything?: boolean;
 }
 
 export type SCDProp = {
@@ -657,6 +756,12 @@ export interface Context {
     incrementUserCount(): void;
     incrementEventCount(): void;
     isBatchMode(): boolean;
+
+    // Progress callback
+    /** Fire a progress update to the caller's `onProgress` callback (throttled, fault-tolerant). */
+    reportProgress(update: ProgressUpdate): void;
+    /** Return the progress callback summary (updates delivered, errors, disabled flag). */
+    getProgressSummary(): ProgressSummary;
 }
 
 /**
@@ -796,6 +901,22 @@ export interface Funnel {
      * the time it takes (on average) to convert in hours
      */
     timeToConvert?: number;
+    /**
+     * Mixpanel-style conversion window cap, in DAYS. Funnel-step events after step 0 must
+     * land within `conversionWindowDays * 86400000` ms of step 0's timestamp (strict `<`,
+     * matching `is_within_conversion_window` in `backend/arb/reader/funnels/conversion_window.cpp`).
+     *
+     * Default: 30 (Mixpanel UI default).
+     *
+     * If unset and `timeToConvert / 24 >= 30`, the validator auto-bumps to
+     * `min(180, ceil(timeToConvert / 24 * 1.5))` and warns. Hard cap: 180 days
+     * (Mixpanel's maximum). Validator throws if explicitly set above 180.
+     *
+     * The generator caps funnel runs at `conversionWindowDays * 86400000 - 1` ms (1ms slack
+     * to clear the strict-`<` boundary). The verifier (`verifyDungeon`) reads this field
+     * and applies it automatically when emulating funnel breakdowns.
+     */
+    conversionWindowDays?: number;
     /**
      * funnel properties go onto each event in the funnel and are held constant
      */
@@ -834,6 +955,32 @@ export interface Funnel {
 	 * @see AttemptsConfig
 	 */
 	attempts?: AttemptsConfig;
+
+	// v1.5.0 — funnel extensions
+	/**
+	 * v1.5.0 — Events that terminate the funnel attempt for non-converters. The generator
+	 * stamps 1-2 cloned exclusion events between the last completed step and where the next
+	 * step would have been; the verifier reads this and applies them as exclusionSteps to
+	 * `evaluateFunnel`. Each entry MUST be declared in `events[]` (schema-first) — the
+	 * validator throws otherwise.
+	 */
+	exclusionEvents?: string[];
+	/**
+	 * v1.5.0 — Verifier-only hint. When `true`, the verifier evaluates with reentry
+	 * enabled (counts every completion). Generator behavior unchanged.
+	 */
+	reentry?: boolean;
+	/**
+	 * v1.5.0 — Verifier-only hint. Per-step property conditions; the verifier mutates
+	 * its step list to attach `where`-clauses at the matching index. Generator behavior
+	 * unchanged.
+	 */
+	stepFilters?: Record<number, {
+		prop: string;
+		op: 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains';
+		value: unknown;
+	}>;
+
 	/** @internal Resolved experiment config set by config-validator. */
 	_experiment?: { name: string; variants: Array<{ name: string; conversionMultiplier: number; ttcMultiplier: number; weight: number }>; startUnix: number | null };
 	/** @internal Set by funnels.js during experiment handling. */
@@ -1053,8 +1200,61 @@ export type Result = {
     userCount?: number;
     groupCount?: number;
     avgEPS?: number;
+    /** Progress callback summary. Only present when `onProgress` was provided. */
+    progress?: ProgressSummary;
 };
 
+// ============= Progress Callback Types =============
+
+/** Discriminator for progress update types. */
+export type ProgressPhase = "generation" | "import" | "step";
+
+/** Progress update emitted during user/event generation (throttled to `progressInterval`). */
+export interface ProgressGeneration {
+    phase: "generation";
+    users: number;
+    events: number;
+    eps: number;
+    memory: string;
+    elapsed: string;
+    percentComplete: number;
+}
+
+/** Progress update emitted during Mixpanel import (throttled to `progressInterval`). */
+export interface ProgressImport {
+    phase: "import";
+    recordType: string;
+    processed: number;
+    total: number;
+    eps: string;
+    bytesProcessed: number;
+}
+
+/** Progress update emitted at pipeline step boundaries (not throttled). */
+export interface ProgressStep {
+    phase: "step";
+    step: string;
+    status: "start" | "complete";
+    /** Milliseconds elapsed (only present on `status: "complete"`). */
+    duration?: number;
+}
+
+/** Discriminated union of all progress update types. Discriminate on the `phase` field. */
+export type ProgressUpdate = ProgressGeneration | ProgressImport | ProgressStep;
+
+/** Convenience type for the `onProgress` callback signature. */
+export type ProgressCallback = (update: ProgressUpdate) => void;
+
+/** Summary of progress callback activity, included in the job result. */
+export interface ProgressSummary {
+    /** Total number of updates successfully delivered to the callback. */
+    updates: number;
+    /** Number of times the callback threw (0-3; disabled after 3). */
+    errors: number;
+    /** True if the callback was disabled due to repeated failures. */
+    disabled: boolean;
+}
+
 // ============= Advanced Feature Types =============
 
 /**
@@ -1550,7 +1750,7 @@ declare module '@ak--47/dungeon-master/hook-patterns' {
  * | `attributedBy` | `conversionEvent`, `attributionEvent`, `attributionProperty` | `model` (default: `'lastTouch'`) |
  */
 export interface EmulateOptions {
-    type: 'frequencyByFrequency' | 'funnelFrequency' | 'aggregatePerUser' | 'timeToConvert' | 'attributedBy';
+    type: 'frequencyByFrequency' | 'funnelFrequency' | 'aggregatePerUser' | 'timeToConvert' | 'attributedBy' | 'sessionMetrics' | 'retention';
     metricEvent?: string;
     breakdownByFrequencyOf?: string;
     perUser?: boolean;
@@ -1566,6 +1766,74 @@ export interface EmulateOptions {
     attributionEvent?: string;
     attributionProperty?: string;
     model?: 'firstTouch' | 'lastTouch';
+    /**
+     * Pre-built device→user map (e.g. from `buildIdentityMap(profiles)`). When omitted but
+     * `profiles` are supplied with `device_ids`, the map is built automatically. Threaded
+     * through every breakdown type so pre-auth (device_id) events resolve to the same
+     * canonical user as post-auth (user_id) events.
+     */
+    identityMap?: Map<string, string>;
+    /** v1.5.0 — funnel reentry. After completing all steps, reset and continue scanning. Used by funnelFrequency + timeToConvert sequential modes. */
+    reentry?: boolean;
+    /** v1.5.0 — funnel exclusion steps. If an exclusion event fires between specified steps, terminate the attempt. */
+    exclusionSteps?: Array<{ event: string; afterStep?: number; beforeStep?: number }>;
+    /** v1.5.0 — funnel step property tracking. Captures matched event properties at each step into FunnelResult.stepProperties. */
+    trackStepProperties?: boolean | string[];
+    /** v1.5.0 — partition funnel evaluation by `session_id`; only steps in the same session can complete. */
+    sessionScoped?: boolean;
+    /** v1.5.0 — cross-cutting time-bucketed output. Wraps any breakdown type, returning rows tagged with `period` per UTC bucket. */
+    timeBucket?: 'day' | 'week' | 'month';
+    /**
+     * v1.5.0 — when set with `timeBucket`, enumerates EVERY bucket in `[from, to]`
+     * and emits a `{ period, _empty: true }` marker for buckets with no events
+     * (Mixpanel normal_query.cpp emits zero rows for empty intervals). Without
+     * this, only buckets containing events are returned.
+     *
+     * **Empty-row contract:** consumers MUST filter `r._empty` before any
+     * numerical aggregation. Populated rows have full breakdown fields plus
+     * `period`; empty rows have ONLY `period` and `_empty: true`.
+     */
+    timeBucketRange?: { from: number | string; to: number | string };
+    /** v1.5.0 — sessionMetrics: filter to sessions containing this event. Omit for all sessions. */
+    metrics?: Array<'count' | 'duration' | 'eventsPerSession'>;
+
+    // v1.5.0 retention extensions
+    /** Retention birth event name. */
+    cohortEvent?: string;
+    /** Retention return event name. */
+    returnEvent?: string;
+    /** Day buckets to check (offsets from birth, ≥1). */
+    dayBuckets?: number[];
+    /** Segment cohort by birth event property value (Mixpanel segment_event=FIRST). */
+    segmentBy?: string;
+    /** CARRY_FORWARD unbounded mode — once retained, counted on all later buckets. */
+    carry_forward?: boolean;
+    /**
+     * v1.5.0 — Mixpanel `birth_can_retain` (retention_query.cpp:1097-1109). Default
+     * `false`: a return event at the EXACT birth ms is NOT counted (strict `<`).
+     * Set `true` to count exact-birth-ms returns (rare; usually a same-event-as-birth
+     * pattern requires COMPOUNDED retention which is not supported here).
+     */
+    birthCanRetain?: boolean;
+}
+
+/** v1.5.0 — config for `emulateBreakdown({ type: 'retention' })`. */
+export interface RetentionConfig extends EmulateOptions {
+    type: 'retention';
+    cohortEvent: string;
+    returnEvent: string;
+    dayBuckets: number[];
+    segmentBy?: string;
+    carry_forward?: boolean;
+}
+
+/** v1.5.0 — config for `emulateBreakdown({ type: 'sessionMetrics' })`. */
+export interface SessionMetricsConfig extends EmulateOptions {
+    type: 'sessionMetrics';
+    /** Optional event filter — only sessions containing this event qualify. */
+    event?: string;
+    /** Which metrics to compute. Default: `['count', 'duration', 'eventsPerSession']`. */
+    metrics?: Array<'count' | 'duration' | 'eventsPerSession'>;
 }
 
 declare module '@ak--47/dungeon-master/verify' {
@@ -1573,6 +1841,48 @@ declare module '@ak--47/dungeon-master/verify' {
     export function verifyDungeon(config: Dungeon, checks: Array<{ name: string; breakdown: EmulateOptions; assert: (rows: Array<Record<string, unknown>>, ctx: { events: EventSchema[]; profiles: UserProfile[] }) => { pass: boolean; detail?: string } }>): Promise<{ pass: boolean; results: Array<{ name: string; pass: boolean; detail?: string; rows?: Array<Record<string, unknown>> }>; schemaReport: SchemaReport }>;
     export function deriveExpectedSchema(config: Dungeon): Map<string, Set<string>>;
     export function validateSchema(events: EventSchema[], config: Dungeon): SchemaReport;
+    /** Build a `Map<device_id, canonical_user_id>` by inverting each profile's `device_ids` array. */
+    export function buildIdentityMap(profiles: UserProfile[]): Map<string, string>;
+    /** Resolve canonical user id for an event using the identity map (device→user merge). */
+    export function resolveUserId(event: EventSchema | Record<string, unknown>, identityMap?: Map<string, string>): string | undefined;
+
+    /** Funnel step type — string OR `{ event, where? }` for step-level property filters. */
+    export type FunnelStep = string | { event: string; where?: { prop: string; op: 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains'; value: unknown } };
+    /** Exclusion step config — fires between `afterStep` and `beforeStep` to terminate the funnel attempt. */
+    export interface ExclusionStep { event: string; afterStep?: number; beforeStep?: number }
+    /** Greedy single-pass funnel evaluator options. */
+    export interface FunnelOptions {
+        conversionWindowMs?: number;
+        graceperiod?: boolean;
+        reentry?: boolean;
+        exclusionSteps?: ExclusionStep[];
+        trackStepProperties?: boolean | string[];
+        countMode?: 'uniques' | 'totals';
+        sessionScoped?: boolean;
+    }
+    /** Per-attempt funnel result. */
+    export interface FunnelResult {
+        completed: boolean;
+        reached: number;
+        stepEvents: Array<Record<string, unknown> | null>;
+        stepTimes: Array<number | null>;
+        ttcMs: number | null;
+        completions: number;
+        stepProperties?: Array<Record<string, unknown>>;
+        sessionId?: string;
+    }
+    /** 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`. */
+    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. */
+    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 } };
+    /** Test whether an event qualifies for a step's where-clause. */
+    export function matchesStepFilter(event: Record<string, unknown>, where?: { prop: string; op: string; value: unknown }): boolean;
+    /** Partition events into UTC `day` / `week` (ISO) / `month` buckets. */
+    export function partitionByTimeBucket(events: Array<Record<string, unknown>>, bucket: 'day' | 'week' | 'month'): Array<{ period: string; events: Array<Record<string, unknown>> }>;
 
     interface SchemaReport {
         pass: boolean;

package/scripts/smoke-test-all.mjs

@@ -1,162 +0,0 @@
-#!/usr/bin/env node
-/**
- * Smoke-test runner — runs every dungeon at tiny scale in parallel to verify it
- * loads, generates events, and writes output without crashing.
- *
- * Default scale: 100 users, 1000 events per dungeon. NOT for verification —
- * use scripts/verify-runner.mjs at full fidelity for that.
- *
- * Usage:
- *   node scripts/smoke-test-all.mjs
- *   node scripts/smoke-test-all.mjs --dir dungeons/vertical    # default
- *   node scripts/smoke-test-all.mjs --dir dungeons/technical
- *   node scripts/smoke-test-all.mjs --dir dungeons             # both subdirs
- *   node scripts/smoke-test-all.mjs --concurrency 4            # default: cpu count
- *   node scripts/smoke-test-all.mjs --users 500 --events 5000  # override scale
- *
- * Output: per-dungeon PASS/FAIL line + a final summary table. Spawns each
- * dungeon as a child node process so a crash in one doesn't abort the run.
- */
-import { spawn } from 'child_process';
-import { readdirSync, statSync, rmSync, existsSync, mkdirSync } from 'fs';
-import path from 'path';
-import os from 'os';
-
-const args = process.argv.slice(2);
-function arg(name, fallback) {
-	const i = args.indexOf(`--${name}`);
-	return i === -1 ? fallback : args[i + 1];
-}
-
-const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
-const dirArg = arg('dir', 'dungeons/vertical');
-const numUsers = parseInt(arg('users', '100'), 10);
-const numEvents = parseInt(arg('events', '1000'), 10);
-const concurrency = parseInt(arg('concurrency', String(Math.max(2, os.cpus().length))), 10);
-const keep = args.includes('--keep');
-
-function findDungeons(dir) {
-	const abs = path.resolve(ROOT, dir);
-	if (!existsSync(abs)) return [];
-	const stat = statSync(abs);
-	if (stat.isFile()) return [abs];
-	const out = [];
-	for (const entry of readdirSync(abs)) {
-		const full = path.join(abs, entry);
-		const s = statSync(full);
-		if (s.isDirectory()) out.push(...findDungeons(full));
-		else if (entry.endsWith('.js')) out.push(full);
-	}
-	return out;
-}
-
-const dungeons = findDungeons(dirArg).sort();
-if (dungeons.length === 0) {
-	console.error(`No dungeons found under ${dirArg}`);
-	process.exit(1);
-}
-
-const dataDir = path.join(ROOT, 'data');
-mkdirSync(dataDir, { recursive: true });
-
-const RUNNER = `
-import generate from '${path.join(ROOT, 'index.js')}';
-// With node -e, process.argv = [nodePath, ...userArgs] — no script slot.
-const [dungeonPath, name, numUsers, numEvents] = process.argv.slice(1);
-const r = await generate(dungeonPath, {
-	numUsers: parseInt(numUsers, 10),
-	numEvents: parseInt(numEvents, 10),
-	avgEventsPerUserPerDay: undefined,  // force numEvents path
-	writeToDisk: true,
-	name,
-	format: 'json',
-	verbose: false,
-	concurrency: 1,
-	token: '',
-	serviceAccount: 'fake', serviceSecret: 'fake', projectId: '1',
-});
-console.log(JSON.stringify({ eventCount: r.eventCount, userCount: r.userCount }));
-`;
-
-function runOne(dungeonPath) {
-	const base = path.basename(dungeonPath, '.js');
-	const namePrefix = `smoke-${base}`;
-	return new Promise(resolve => {
-		const start = Date.now();
-		const child = spawn(
-			process.execPath,
-			['--input-type=module', '-e', RUNNER, dungeonPath, namePrefix, String(numUsers), String(numEvents)],
-			{ cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'] }
-		);
-		let out = '';
-		let err = '';
-		child.stdout.on('data', d => { out += d.toString(); });
-		child.stderr.on('data', d => { err += d.toString(); });
-		child.on('close', code => {
-			const ms = Date.now() - start;
-			let result;
-			try {
-				const lastLine = out.trim().split('\n').filter(Boolean).pop() || '{}';
-				result = JSON.parse(lastLine);
-			} catch {
-				result = {};
-			}
-			const ok = code === 0 && result.eventCount > 0;
-			if (!keep) {
-				try {
-					for (const f of readdirSync(dataDir)) {
-						if (f.startsWith(`${namePrefix}-`)) rmSync(path.join(dataDir, f));
-					}
-				} catch {}
-			}
-			resolve({
-				dungeon: path.relative(ROOT, dungeonPath),
-				ok,
-				code,
-				ms,
-				eventCount: result.eventCount || 0,
-				userCount: result.userCount || 0,
-				err: ok ? '' : (err.trim().split('\n').slice(-3).join(' | ') || `exit ${code}`),
-			});
-		});
-	});
-}
-
-console.log(`Smoke test: ${dungeons.length} dungeons, ${numUsers} users / ${numEvents} events each, concurrency=${concurrency}`);
-const queue = [...dungeons];
-const results = [];
-const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
-	while (queue.length) {
-		const d = queue.shift();
-		const res = await runOne(d);
-		const tag = res.ok ? 'PASS' : 'FAIL';
-		console.log(`  [${tag}] ${path.basename(res.dungeon)} — ${res.eventCount} events, ${res.userCount} users, ${(res.ms / 1000).toFixed(2)}s${res.ok ? '' : ` — ${res.err}`}`);
-		results.push(res);
-	}
-});
-await Promise.all(workers);
-
-results.sort((a, b) => a.dungeon.localeCompare(b.dungeon));
-const fails = results.filter(r => !r.ok);
-
-console.log('\n┌─────────────────────────────────────────────────┬───────┬────────┬───────┬──────┐');
-console.log('│ Dungeon                                         │ State │ Events │ Users │   ms │');
-console.log('├─────────────────────────────────────────────────┼───────┼────────┼───────┼──────┤');
-for (const r of results) {
-	const name = r.dungeon.padEnd(47).slice(0, 47);
-	const state = (r.ok ? 'PASS' : 'FAIL').padEnd(5);
-	const ev = String(r.eventCount).padStart(6);
-	const u = String(r.userCount).padStart(5);
-	const ms = String(r.ms).padStart(4);
-	console.log(`│ ${name} │ ${state} │ ${ev} │ ${u} │ ${ms} │`);
-}
-console.log('└─────────────────────────────────────────────────┴───────┴────────┴───────┴──────┘');
-
-console.log(`\n${results.length - fails.length}/${results.length} passed`);
-if (fails.length > 0) {
-	console.log('\nFailures:');
-	for (const f of fails) {
-		console.log(`  ✗ ${f.dungeon}: ${f.err}`);
-	}
-	process.exit(1);
-}