@synode/core 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1093 @@
+import { a as generateDataset, c as SynodeContext, d as formatErrorMessage, f as levenshtein, i as defineDataset, l as SynodeError, n as generateDelay, o as definePersona, p as suggestClosest, r as shouldBounce, s as generatePersona, t as Engine, u as buildNotFoundSuggestion } from "./engine-SRByMZvP.mjs";
+import { cpus } from "node:os";
+import { Worker } from "node:worker_threads";
+import path, { extname, join } from "node:path";
+import fs, { access, writeFile } from "node:fs/promises";
+import { accessSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+//#region src/generators/builder.ts
+/**
+* Defines a new journey.
+* @param config The journey configuration.
+* @returns The configured journey object.
+* @see {@link Journey}
+*/
+function defineJourney(config) {
+	return config;
+}
+/**
+* Defines a new adventure.
+* @param config The adventure configuration.
+* @returns The configured adventure object.
+* @see {@link Adventure}
+*/
+function defineAdventure(config) {
+	return config;
+}
+/**
+* Defines a new action.
+* @param config The action configuration.
+* @returns The configured action object.
+* @see {@link Action}
+* @see {@link ActionDefinition}
+*/
+function defineAction(config) {
+	if (config.handler) return {
+		id: config.id,
+		name: config.name,
+		handler: config.handler,
+		timeSpan: config.timeSpan,
+		bounceChance: config.bounceChance
+	};
+	return {
+		id: config.id,
+		name: config.name,
+		timeSpan: config.timeSpan,
+		bounceChance: config.bounceChance,
+		handler: async (context) => {
+			const payload = {};
+			if (config.fields) for (const [key, generator] of Object.entries(config.fields)) if (typeof generator === "function") payload[key] = await generator(context, payload);
+			else payload[key] = generator;
+			return [{
+				id: context.generateId("event"),
+				userId: context.userId,
+				sessionId: context.sessionId,
+				name: config.name,
+				timestamp: context.now(),
+				payload
+			}];
+		}
+	};
+}
+
+//#endregion
+//#region src/generators/fields.ts
+/**
+* Returns a value generated by Faker.js using the context's locale.
+* @param generator Function that takes a Faker instance and returns a value.
+*/
+function fake(generator) {
+	return (context) => {
+		return generator(context.faker);
+	};
+}
+/**
+* Returns one of the provided options randomly.
+*/
+function oneOf(options) {
+	return () => {
+		return options[Math.floor(Math.random() * options.length)];
+	};
+}
+/**
+* Returns true with the given probability (0-1).
+*/
+function chance(probability) {
+	return () => {
+		return Math.random() < probability;
+	};
+}
+/**
+* Returns a value based on weighted probabilities.
+* @param options Map of value to weight (weights should sum to 1, but will be normalized if not)
+*/
+function weighted(options) {
+	return () => {
+		const entries = Object.entries(options);
+		const totalWeight = entries.reduce((sum, [, weight]) => sum + weight, 0);
+		let random = Math.random() * totalWeight;
+		for (const [value, weight] of entries) {
+			random -= weight;
+			if (random <= 0) return value;
+		}
+		return entries[entries.length - 1][0];
+	};
+}
+
+//#endregion
+//#region src/execution/pool.ts
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+/**
+* Resolves the worker script path. Uses the compiled `.mjs` in dist when available,
+* falling back to the TypeScript source for development with tsx.
+*
+* Checks two locations for the compiled worker:
+* 1. Same directory as pool (works when running from dist/)
+* 2. Equivalent dist/ path (works when running from src/ during dev/test)
+*
+* @returns Absolute path to the worker script
+*/
+function resolveWorkerScript() {
+	const localMjs = join(__dirname, "worker.mjs");
+	try {
+		accessSync(localMjs);
+		return localMjs;
+	} catch {}
+	const distMjs = __dirname.replace(/src[\\/]/, "dist/") + "worker.mjs";
+	try {
+		accessSync(distMjs);
+		return distMjs;
+	} catch {}
+	return join(__dirname, "worker.ts");
+}
+/**
+* Serializes a Map of datasets into plain objects for structured clone transfer.
+*
+* @param datasets - Map of dataset ID to Dataset
+* @returns Array of serialized datasets
+*/
+function serializeDatasets(datasets) {
+	if (!datasets || datasets.size === 0) return [];
+	const result = [];
+	for (const dataset of datasets.values()) result.push({
+		id: dataset.id,
+		name: dataset.name,
+		rows: dataset.rows
+	});
+	return result;
+}
+/**
+* Rehydrates a Date value that may have been stringified during structured clone.
+* Structured clone preserves Dates natively, but this provides a safety net
+* for edge cases where timestamps arrive as ISO strings.
+*
+* @param value - A Date object or ISO string timestamp
+* @returns A proper Date instance
+*/
+function rehydrateDate(value) {
+	if (value instanceof Date) return value;
+	return new Date(value);
+}
+/**
+* Manages a pool of worker threads for parallel user generation.
+* Distributes users evenly across workers, collects events via message passing,
+* and writes them through the configured output adapter.
+*/
+var WorkerPool = class {
+	options;
+	/**
+	* @param options - Pool configuration including module path, user count, and adapter
+	*/
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* Validates the worker module path exists on disk.
+	*
+	* @throws Error if the module path does not exist
+	*/
+	async validateModule() {
+		try {
+			await access(this.options.workerModule);
+		} catch {
+			throw new Error(`Worker module not found: ${this.options.workerModule}`);
+		}
+	}
+	/**
+	* Spawns all worker threads, distributes user ranges, collects events,
+	* and waits for completion.
+	*
+	* @throws Error if any worker fails with an unrecoverable error
+	*/
+	async run() {
+		await this.validateModule();
+		const { workerModule, userCount, workerCount, adapter, telemetry, startDate, endDate } = this.options;
+		const serializedDatasets = serializeDatasets(this.options.preGeneratedDatasets);
+		const usersPerWorker = Math.ceil(userCount / workerCount);
+		const workerScript = resolveWorkerScript();
+		const isTypeScript = extname(workerScript) === ".ts";
+		const errors = [];
+		const workers = [];
+		const workerPromises = Array.from({ length: workerCount }, (_, i) => {
+			const userStart = i * usersPerWorker;
+			const userEnd = Math.min(userStart + usersPerWorker, userCount);
+			if (userStart >= userCount) return Promise.resolve();
+			const worker = new Worker(workerScript, {
+				workerData: {
+					workerModule,
+					userStart,
+					userEnd,
+					startDate,
+					endDate,
+					serializedDatasets
+				},
+				execArgv: isTypeScript ? ["--import", "tsx"] : extname(workerModule) === ".ts" ? ["--experimental-strip-types"] : []
+			});
+			workers.push(worker);
+			return this.listenToWorker(worker, adapter, telemetry ?? null, errors);
+		});
+		const results = await Promise.allSettled(workerPromises);
+		for (const result of results) if (result.status === "rejected") {
+			const reason = result.reason;
+			errors.push(reason instanceof Error ? reason : new Error(String(reason)));
+		}
+		if (errors.length > 0) {
+			const combined = errors.map((e) => e.message).join("\n");
+			throw new Error(`Worker pool failed with ${String(errors.length)} error(s):\n${combined}`);
+		}
+	}
+	/**
+	* Listens to a single worker's messages and routes them to the adapter/telemetry.
+	*
+	* @param worker - The Worker thread to listen to
+	* @param adapter - Output adapter for writing events
+	* @param telemetry - Optional telemetry collector
+	* @param errors - Mutable array to collect errors from failed workers
+	* @returns Promise that resolves when the worker sends 'done' or rejects on error
+	*/
+	listenToWorker(worker, adapter, telemetry, errors) {
+		return new Promise((resolve, reject) => {
+			worker.on("message", (msg) => {
+				switch (msg.type) {
+					case "events":
+						for (const event of msg.events) {
+							event.timestamp = rehydrateDate(event.timestamp);
+							Promise.resolve(adapter.write(event)).catch((err) => {
+								const writeError = /* @__PURE__ */ new Error(`Adapter write failed: ${err instanceof Error ? err.message : String(err)}`);
+								errors.push(writeError);
+							});
+						}
+						if (telemetry) {
+							let remaining = msg.events.length;
+							while (remaining-- > 0) telemetry.recordEvent();
+						}
+						break;
+					case "user-started":
+						if (telemetry) telemetry.recordUserStarted();
+						break;
+					case "user-completed":
+						if (telemetry) telemetry.recordUserCompleted();
+						break;
+					case "error": {
+						const workerError = new Error(msg.message);
+						if (msg.stack) workerError.stack = msg.stack;
+						errors.push(workerError);
+						worker.terminate();
+						reject(workerError);
+						break;
+					}
+					case "done":
+						resolve();
+						break;
+				}
+			});
+			worker.on("error", (err) => {
+				errors.push(err);
+				reject(err);
+			});
+			worker.on("exit", (code) => {
+				if (code !== 0) {
+					const exitError = /* @__PURE__ */ new Error(`Worker exited with code ${String(code)}`);
+					errors.push(exitError);
+					reject(exitError);
+				}
+			});
+		});
+	}
+};
+
+//#endregion
+//#region src/adapters/console.ts
+/**
+* Adapter that writes events to the console as pretty-printed JSON.
+*
+* @example
+* ```ts
+* await generate(journey, { users: 10, adapter: new ConsoleAdapter() });
+* ```
+*/
+var ConsoleAdapter = class {
+	/** @inheritdoc */
+	write(event) {
+		console.log(JSON.stringify(event, null, 2));
+	}
+};
+
+//#endregion
+//#region src/monitoring/telemetry.ts
+/**
+* Collects telemetry data during generation runs.
+*/
+var TelemetryCollector = class {
+	startTime;
+	snapshots = [];
+	intervalHandle = null;
+	currentSecondEvents = 0;
+	totalEvents = 0;
+	activeUsers = 0;
+	completedUsers = 0;
+	lanes;
+	eventsValidated = 0;
+	eventsValid = 0;
+	eventsInvalid = 0;
+	validationErrors = [];
+	constructor(lanes) {
+		this.startTime = /* @__PURE__ */ new Date();
+		this.lanes = lanes;
+	}
+	/**
+	* Start collecting telemetry data every second.
+	*/
+	start() {
+		this.intervalHandle = setInterval(() => {
+			this.captureSnapshot();
+		}, 1e3);
+	}
+	/**
+	* Stop collecting telemetry data.
+	*/
+	stop() {
+		if (this.intervalHandle) {
+			clearInterval(this.intervalHandle);
+			this.intervalHandle = null;
+		}
+		this.captureSnapshot();
+	}
+	/**
+	* Record that an event was generated.
+	*/
+	recordEvent() {
+		this.currentSecondEvents++;
+		this.totalEvents++;
+	}
+	/**
+	* Record that a user started processing.
+	*/
+	recordUserStarted() {
+		this.activeUsers++;
+	}
+	/**
+	* Record that a user completed processing.
+	*/
+	recordUserCompleted() {
+		this.activeUsers--;
+		this.completedUsers++;
+	}
+	/**
+	* Merge a validation summary from a lane or journey into the collector totals.
+	*
+	* @param summary - Aggregated validation counts and errors to record.
+	*/
+	recordValidationSummary(summary) {
+		this.eventsValidated += summary.eventsValidated;
+		this.eventsValid += summary.eventsValid;
+		this.eventsInvalid += summary.eventsInvalid;
+		for (const err of summary.validationErrors) if (this.validationErrors.length < 50) this.validationErrors.push(err);
+	}
+	/**
+	* Generate the final telemetry report.
+	*/
+	getReport() {
+		const endTime = /* @__PURE__ */ new Date();
+		const durationMs = endTime.getTime() - this.startTime.getTime();
+		const averageEventsPerSecond = durationMs > 0 ? this.totalEvents / durationMs * 1e3 : this.totalEvents;
+		return {
+			startTime: this.startTime.toISOString(),
+			endTime: endTime.toISOString(),
+			durationMs,
+			totalUsers: this.completedUsers,
+			totalEvents: this.totalEvents,
+			lanes: this.lanes,
+			averageEventsPerSecond: Number(averageEventsPerSecond.toFixed(2)),
+			snapshots: this.snapshots,
+			activeUsers: this.activeUsers,
+			completedUsers: this.completedUsers,
+			eventsValidated: this.eventsValidated,
+			eventsValid: this.eventsValid,
+			eventsInvalid: this.eventsInvalid,
+			validationErrors: this.validationErrors
+		};
+	}
+	/**
+	* Save the telemetry report to a JSON file.
+	*/
+	async saveReport(filePath) {
+		const report = this.getReport();
+		await writeFile(filePath, JSON.stringify(report, null, 2), "utf-8");
+	}
+	captureSnapshot() {
+		const now = /* @__PURE__ */ new Date();
+		const elapsedMs = now.getTime() - this.startTime.getTime();
+		this.snapshots.push({
+			timestamp: now.toISOString(),
+			elapsedMs,
+			eventsPerSecond: this.currentSecondEvents,
+			totalEvents: this.totalEvents,
+			activeUsers: this.activeUsers,
+			completedUsers: this.completedUsers,
+			lanes: this.lanes
+		});
+		this.currentSecondEvents = 0;
+	}
+};
+
+//#endregion
+//#region src/monitoring/event-validation.ts
+const MAX_STORED_ERRORS = 50;
+/**
+* Error thrown when an event fails schema validation in strict mode.
+*/
+var SynodeValidationError = class extends Error {
+	event;
+	issues;
+	constructor(options) {
+		super(options.message);
+		this.name = "SynodeValidationError";
+		this.event = options.event;
+		this.issues = options.issues;
+	}
+};
+/**
+* Wraps `z.object()` for defining event payload schemas.
+*
+* @param shape - Zod raw shape describing the expected payload fields
+* @returns A ZodObject schema
+*
+* @example
+* ```typescript
+* const pageViewSchema = defineEventSchema({
+*   url: z.string().url(),
+*   referrer: z.string().optional(),
+* });
+* ```
+*/
+function defineEventSchema(shape) {
+	return z.object(shape);
+}
+/**
+* Creates a fresh zeroed validation summary.
+*
+* @returns An empty ValidationSummary ready for accumulation
+*/
+function createValidationSummary() {
+	return {
+		eventsValidated: 0,
+		eventsValid: 0,
+		eventsInvalid: 0,
+		validationErrors: []
+	};
+}
+/**
+* Converts Zod v4 issues to ValidationIssue instances.
+*/
+function toValidationIssues(zodIssues) {
+	return zodIssues.map((issue) => ({
+		path: issue.path.map((segment) => typeof segment === "symbol" ? String(segment) : segment),
+		message: issue.message,
+		code: issue.code
+	}));
+}
+/**
+* Resolves the correct schema for an event based on the config.
+* Returns undefined if no schema applies to this event.
+*/
+function resolveSchema(event, config) {
+	if (config.schema instanceof z.ZodType) return config.schema;
+	return config.schema[event.name];
+}
+/**
+* Records a validation failure in the summary, respecting the MAX_STORED_ERRORS cap.
+*/
+function recordFailure(summary, event, issues) {
+	summary.eventsInvalid++;
+	for (const issue of issues) if (summary.validationErrors.length < MAX_STORED_ERRORS) summary.validationErrors.push({
+		eventName: event.name,
+		path: issue.path.join("."),
+		message: issue.message
+	});
+}
+/**
+* Validates an event against its configured schema.
+*
+* Behavior depends on the configured mode:
+* - `strict` (default): throws {@link SynodeValidationError} on first failure
+* - `warn`: returns the event but records failure in the summary
+* - `skip`: returns `undefined` (event is dropped) and records failure in the summary
+*
+* Events with no matching schema in a per-name map are passed through without validation.
+*
+* @param event - The event to validate
+* @param config - Schema and mode configuration
+* @param summary - Mutable summary accumulating validation statistics
+* @returns The event if it passes or is kept (warn mode), or undefined if skipped
+* @throws SynodeValidationError in strict mode when validation fails
+*/
+function validateEvent(event, config, summary) {
+	const schema = resolveSchema(event, config);
+	if (!schema) return event;
+	summary.eventsValidated++;
+	const result = schema.safeParse(event.payload);
+	if (result.success) {
+		summary.eventsValid++;
+		return event;
+	}
+	const issues = toValidationIssues(result.error.issues);
+	const mode = config.mode ?? "strict";
+	if (mode === "strict") {
+		recordFailure(summary, event, issues);
+		throw new SynodeValidationError({
+			message: `Event '${event.name}' failed schema validation: ${issues.map((i) => i.message).join("; ")}`,
+			event,
+			issues
+		});
+	}
+	if (mode === "warn") {
+		recordFailure(summary, event, issues);
+		return event;
+	}
+	recordFailure(summary, event, issues);
+}
+
+//#endregion
+//#region src/execution/runner.ts
+/**
+* Returns a random Date between start (inclusive) and end (inclusive).
+*/
+function randomDateInRange(start, end) {
+	const startMs = start.getTime();
+	const endMs = end.getTime();
+	return new Date(startMs + Math.random() * (endMs - startMs));
+}
+/**
+* Pre-generates datasets from definitions and merges with preloaded datasets.
+*
+* @param datasets - Optional dataset definitions to generate
+* @param preloaded - Optional pre-populated datasets to include
+* @returns Map of dataset ID to generated/preloaded Dataset
+*/
+async function prepareDatasets(datasets, preloaded) {
+	const result = /* @__PURE__ */ new Map();
+	if (datasets && datasets.length > 0) {
+		const tempContext = new SynodeContext();
+		for (const datasetDef of datasets) {
+			const dataset = await generateDataset(datasetDef, tempContext);
+			result.set(dataset.id, dataset);
+		}
+	}
+	if (preloaded) for (const dataset of preloaded) result.set(dataset.id, dataset);
+	return result;
+}
+/**
+* Creates a SynodeContext for a single user, hydrating persona attributes
+* and registering pre-generated datasets.
+*
+* @param persona - Optional persona definition for generating user attributes
+* @param preGeneratedDatasets - Pre-generated datasets to register with the context
+* @param startDate - Optional start of date range for random start time
+* @param endDate - Optional end of date range for random start time
+* @returns A fully initialized SynodeContext
+*/
+async function createUserContext(persona, preGeneratedDatasets, startDate, endDate) {
+	const userStartTime = startDate && endDate ? randomDateInRange(startDate, endDate) : /* @__PURE__ */ new Date();
+	let context;
+	if (persona) {
+		const personaData = await generatePersona(persona, new SynodeContext());
+		context = new SynodeContext(userStartTime, void 0, typeof personaData.attributes.locale === "string" ? personaData.attributes.locale : "en");
+		for (const [key, value] of Object.entries(personaData.attributes)) context.set(key, value);
+	} else context = new SynodeContext(userStartTime);
+	for (const dataset of preGeneratedDatasets.values()) context.registerDataset(dataset);
+	return context;
+}
+/**
+* Runs all journeys on a context, writing events to the adapter.
+* Wraps adapter.write() failures in SynodeError with code ADAPTER_WRITE_ERROR.
+*
+* @param journeys - Journeys to execute
+* @param context - The user's execution context
+* @param adapter - Output adapter to write events to
+* @param telemetry - Optional telemetry collector for recording events
+* @param eventSchema - Optional event schema validation configuration
+* @param summary - Optional mutable validation summary for accumulating results
+*/
+async function processUser(journeys, context, adapter, telemetry, eventSchema, summary) {
+	for (const journey of journeys) {
+		const engine = new Engine(journey);
+		for await (const event of engine.run(context)) {
+			if (eventSchema && summary) {
+				if (!validateEvent(event, eventSchema, summary)) continue;
+			}
+			try {
+				await adapter.write(event);
+			} catch (error) {
+				throw new SynodeError({
+					code: "ADAPTER_WRITE_ERROR",
+					message: `Adapter write failed for event '${event.name}': ${error instanceof Error ? error.message : String(error)}`,
+					path: [journey.id],
+					suggestion: "Check the output adapter for write errors or capacity issues",
+					cause: error
+				});
+			}
+			if (telemetry) telemetry.recordEvent();
+		}
+	}
+}
+/**
+* Generates synthetic data based on the provided journey configuration.
+*/
+async function generate(journey, options) {
+	const journeys = Array.isArray(journey) ? journey : [journey];
+	if (options.startDate && !options.endDate) throw new Error("startDate requires endDate to be provided");
+	if (options.endDate && !options.startDate) throw new Error("endDate requires startDate to be provided");
+	if (options.startDate && options.endDate && options.startDate.getTime() >= options.endDate.getTime()) throw new Error("startDate must be before endDate");
+	if (!Number.isFinite(options.users) || options.users < 0 || options.users > 1e7) throw new Error("users must be a finite number between 0 and 10,000,000");
+	if (options.lanes !== void 0 && (!Number.isFinite(options.lanes) || options.lanes < 1 || options.lanes > 1e3)) throw new Error("lanes must be a finite number between 1 and 1,000");
+	if (options.workers !== void 0 && !options.workerModule) throw new Error("workers option requires workerModule to be set");
+	if (options.workers !== void 0 && (!Number.isFinite(options.workers) || options.workers < 1 || options.workers > 1024)) throw new Error("workers must be a finite number between 1 and 1,024");
+	const adapter = options.adapter ?? new ConsoleAdapter();
+	const userCount = options.users;
+	const lanes = options.lanes ?? 1;
+	const debug = options.debug ?? false;
+	const telemetryPath = options.telemetryPath ?? "./telemetry-report.json";
+	const telemetry = debug ? new TelemetryCollector(lanes) : null;
+	if (telemetry) telemetry.start();
+	const preGeneratedDatasets = await prepareDatasets(options.datasets, options.preloadedDatasets);
+	const summary = options.eventSchema ? createValidationSummary() : null;
+	if (options.workerModule) await new WorkerPool({
+		workerModule: options.workerModule,
+		userCount,
+		workerCount: options.workers ?? cpus().length,
+		adapter,
+		telemetry,
+		startDate: options.startDate?.toISOString(),
+		endDate: options.endDate?.toISOString(),
+		preGeneratedDatasets
+	}).run();
+	else if (lanes > 1) await runParallel(journeys, userCount, lanes, options.persona, preGeneratedDatasets, adapter, telemetry, options.startDate, options.endDate, options.eventSchema, summary);
+	else await runSequential(journeys, userCount, options.persona, preGeneratedDatasets, adapter, telemetry, options.startDate, options.endDate, options.eventSchema, summary);
+	if (summary && options.eventSchema?.mode === "warn" && summary.eventsInvalid > 0) console.error(`[synode] Validation: ${String(summary.eventsValid)} passed, ${String(summary.eventsInvalid)} failed out of ${String(summary.eventsValidated)} checked`);
+	if (telemetry && summary) telemetry.recordValidationSummary(summary);
+	if (adapter.close) await adapter.close();
+	if (telemetry) {
+		telemetry.stop();
+		await telemetry.saveReport(telemetryPath);
+	}
+}
+/**
+* Run generation sequentially in the main thread.
+*/
+async function runSequential(journeys, userCount, persona, preGeneratedDatasets, adapter, telemetry, startDate, endDate, eventSchema, summary) {
+	for (let i = 0; i < userCount; i++) {
+		if (telemetry) telemetry.recordUserStarted();
+		await processUser(journeys, await createUserContext(persona, preGeneratedDatasets, startDate, endDate), adapter, telemetry, eventSchema, summary ?? void 0);
+		if (telemetry) telemetry.recordUserCompleted();
+	}
+}
+/**
+* Run generation in parallel using concurrent async execution.
+* Note: This uses Promise.all for concurrent execution in the main thread.
+* For true multi-core parallelism, worker threads would require serializable
+* journey definitions (e.g., loaded from file paths rather than in-memory objects).
+*/
+async function runParallel(journeys, userCount, lanes, persona, preGeneratedDatasets, adapter, telemetry, startDate, endDate, eventSchema, summary) {
+	const usersPerLane = Math.ceil(userCount / lanes);
+	const lanePromises = [];
+	for (let laneIndex = 0; laneIndex < lanes; laneIndex++) {
+		const userStart = laneIndex * usersPerLane;
+		const userEnd = Math.min(userStart + usersPerLane, userCount);
+		if (userStart >= userCount) break;
+		const lanePromise = (async () => {
+			for (let i = userStart; i < userEnd; i++) {
+				if (telemetry) telemetry.recordUserStarted();
+				await processUser(journeys, await createUserContext(persona, preGeneratedDatasets, startDate, endDate), adapter, telemetry, eventSchema, summary ?? void 0);
+				if (telemetry) telemetry.recordUserCompleted();
+			}
+		})();
+		lanePromises.push(lanePromise);
+	}
+	await Promise.all(lanePromises);
+}
+
+//#endregion
+//#region src/monitoring/validation.ts
+const ActionSchema = z.object({
+	id: z.string().min(1).describe("Unique identifier for this action"),
+	name: z.string().min(1).describe("Event name this action generates (e.g., \"product_viewed\", \"checkout_completed\")"),
+	handler: z.function().describe("Function returning Event[] or Promise<Event[]>. Receives Context as argument.")
+});
+const AdventureSchema = z.object({
+	id: z.string().min(1).describe("Unique identifier for this adventure within its journey"),
+	name: z.string().min(1).describe("Human-readable adventure name (e.g., \"Browsing Session\")"),
+	actions: z.array(ActionSchema).describe("Ordered list of actions to execute in this adventure. Actions run sequentially.")
+});
+const JourneySchema = z.object({
+	id: z.string().min(1).describe("Unique identifier for this journey. Referenced by other journeys via \"requires\"."),
+	name: z.string().min(1).describe("Human-readable journey name (e.g., \"First Purchase Flow\")"),
+	adventures: z.array(AdventureSchema).describe("Ordered list of adventures in this journey. Adventures run sequentially; each may bounce.")
+});
+/**
+* Validates that a bounce chance value is between 0 and 1 (inclusive).
+*
+* @param value - The bounce chance value to validate
+* @param path - Hierarchical path for error reporting
+* @throws SynodeError with INVALID_BOUNCE_CHANCE code if out of range
+*/
+function validateBounceChance(value, path$1) {
+	if (value === void 0) return;
+	if (value < 0 || value > 1) throw new SynodeError({
+		code: "INVALID_BOUNCE_CHANCE",
+		message: `Bounce chance must be between 0 and 1, got ${String(value)}`,
+		path: path$1,
+		expected: "0 <= bounceChance <= 1",
+		received: String(value)
+	});
+}
+/**
+* Validates that a time span has min <= max.
+*
+* @param timeSpan - The time span to validate
+* @param path - Hierarchical path for error reporting
+* @throws SynodeError with INVALID_TIME_SPAN code if min > max
+*/
+function validateTimeSpan(timeSpan, path$1) {
+	if (timeSpan === void 0) return;
+	if (timeSpan.min > timeSpan.max) throw new SynodeError({
+		code: "INVALID_TIME_SPAN",
+		message: `TimeSpan min (${String(timeSpan.min)}) must not exceed max (${String(timeSpan.max)})`,
+		path: path$1,
+		expected: "min <= max",
+		received: `min=${String(timeSpan.min)}, max=${String(timeSpan.max)}`
+	});
+}
+/**
+* Validates that a suppression period has min <= max.
+*
+* @param period - The suppression period to validate
+* @param path - Hierarchical path for error reporting
+* @throws SynodeError with INVALID_SUPPRESSION_PERIOD code if min > max
+*/
+function validateSuppressionPeriod(period, path$1) {
+	if (period === void 0) return;
+	if (period.min > period.max) throw new SynodeError({
+		code: "INVALID_SUPPRESSION_PERIOD",
+		message: `Suppression period min (${String(period.min)}) must not exceed max (${String(period.max)})`,
+		path: path$1,
+		expected: "min <= max",
+		received: `min=${String(period.min)}, max=${String(period.max)}`
+	});
+}
+/**
+* Detects circular dependencies starting from a journey using depth-first search.
+*
+* @param journeyId - The journey ID to start the search from
+* @param allJourneys - All journeys to check against
+* @throws SynodeError with CIRCULAR_DEPENDENCY code if a cycle is detected
+*/
+function detectCircularDeps(journeyId, allJourneys) {
+	const journeyMap = /* @__PURE__ */ new Map();
+	for (const j of allJourneys) journeyMap.set(j.id, j);
+	const visiting = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	function dfs(currentId, chain) {
+		if (visiting.has(currentId)) throw new SynodeError({
+			code: "CIRCULAR_DEPENDENCY",
+			message: `Circular dependency detected: ${[...chain, currentId].join(" -> ")}`,
+			path: [journeyId]
+		});
+		if (visited.has(currentId)) return;
+		visiting.add(currentId);
+		const journey = journeyMap.get(currentId);
+		if (journey?.requires) for (const reqId of journey.requires) dfs(reqId, [...chain, currentId]);
+		visiting.delete(currentId);
+		visited.add(currentId);
+	}
+	dfs(journeyId, []);
+}
+/**
+* Validates the journey configuration including structural checks for bounce chances,
+* time spans, suppression periods, duplicate IDs, unknown references, and circular dependencies.
+*
+* @param config - The journey configuration to validate
+* @param allJourneys - Optional list of all journeys for cross-journey validation
+* @throws ZodError if basic schema validation fails
+* @throws SynodeError for structural validation failures
+*/
+function validateConfig(config, allJourneys) {
+	JourneySchema.parse(config);
+	const journeyPath = [config.id];
+	validateBounceChance(config.bounceChance, journeyPath);
+	validateSuppressionPeriod(config.suppressionPeriod, journeyPath);
+	const adventureIds = /* @__PURE__ */ new Set();
+	for (const adventure of config.adventures) {
+		if (adventureIds.has(adventure.id)) throw new SynodeError({
+			code: "DUPLICATE_ID",
+			message: `Duplicate Adventure ID found: ${adventure.id}`,
+			path: [...journeyPath, adventure.id]
+		});
+		adventureIds.add(adventure.id);
+		const adventurePath = [...journeyPath, adventure.id];
+		validateBounceChance(adventure.bounceChance, adventurePath);
+		validateTimeSpan(adventure.timeSpan, adventurePath);
+		const actionIds = /* @__PURE__ */ new Set();
+		for (const action of adventure.actions) {
+			if (actionIds.has(action.id)) throw new SynodeError({
+				code: "DUPLICATE_ID",
+				message: `Duplicate Action ID found in adventure '${adventure.id}': ${action.id}`,
+				path: [...adventurePath, action.id]
+			});
+			actionIds.add(action.id);
+			const actionPath = [...adventurePath, action.id];
+			validateBounceChance(action.bounceChance, actionPath);
+			validateTimeSpan(action.timeSpan, actionPath);
+		}
+	}
+	if (allJourneys && config.requires) {
+		const availableIds = allJourneys.map((j) => j.id);
+		for (const reqId of config.requires) if (!availableIds.includes(reqId)) {
+			const suggestion = buildNotFoundSuggestion("journey", reqId, availableIds);
+			throw new SynodeError({
+				code: "UNKNOWN_JOURNEY_REF",
+				message: `Unknown journey reference '${reqId}'`,
+				path: journeyPath,
+				suggestion
+			});
+		}
+		detectCircularDeps(config.id, allJourneys);
+	}
+}
+/**
+* Performs a dry run of the journey for a specified number of users.
+* Returns all generated events in memory.
+*/
+async function dryRun(journey, userCount = 1) {
+	validateConfig(journey);
+	const allEvents = [];
+	for (let i = 0; i < userCount; i++) {
+		const engine = new Engine(journey);
+		for await (const event of engine.run()) allEvents.push(event);
+	}
+	return allEvents;
+}
+
+//#endregion
+//#region src/adapters/memory.ts
+/**
+* Adapter that stores events in memory.
+* Useful for testing and dry runs.
+*
+* @example
+* ```ts
+* const adapter = new InMemoryAdapter();
+* await generate(journey, { users: 10, adapter });
+* console.log(adapter.events.length);
+* ```
+*/
+var InMemoryAdapter = class {
+	events = [];
+	/** @inheritdoc */
+	write(event) {
+		this.events.push(event);
+	}
+	/**
+	* Clears all stored events.
+	*/
+	clear() {
+		this.events.length = 0;
+	}
+};
+
+//#endregion
+//#region src/adapters/callback.ts
+/**
+* Adapter that forwards events to a user-supplied callback function.
+* Supports both synchronous and asynchronous callbacks.
+*
+* @example
+* ```ts
+* const events: Event[] = [];
+* const adapter = new CallbackAdapter((event) => events.push(event));
+* await generate(journey, { users: 10, adapter });
+* ```
+*/
+var CallbackAdapter = class {
+	constructor(callback) {
+		this.callback = callback;
+	}
+	/** @inheritdoc */
+	async write(event) {
+		await this.callback(event);
+	}
+};
+
+//#endregion
+//#region src/dataset-io.ts
+/**
+* Exports a dataset to a string in the specified format.
+*/
+function exportDatasetToString(dataset, format) {
+	switch (format) {
+		case "csv": return generateCSV(dataset);
+		case "json": return JSON.stringify(dataset.rows, null, 2);
+		case "jsonl": return generateJSONL(dataset);
+	}
+}
+/**
+* Imports a dataset from a string in the specified format.
+*/
+function importDatasetFromString(content, format, id = "imported", name = "Imported Dataset") {
+	switch (format) {
+		case "csv": return parseCSVContent(id, name, content);
+		case "json": return parseJSONContent(id, name, content);
+		case "jsonl": return parseJSONLContent(id, name, content);
+	}
+}
+/**
+* Validates that a file path does not escape the given base directory.
+* @throws Error if path traversal is detected.
+*/
+function validateFilePath(filePath, basePath = process.cwd()) {
+	const resolved = path.resolve(basePath, filePath);
+	const baseResolved = path.resolve(basePath);
+	if (!resolved.startsWith(baseResolved + path.sep) && resolved !== baseResolved) throw new Error(`Path traversal detected: '${filePath}' escapes base directory`);
+	return resolved;
+}
+/**
+* Exports a dataset to a file in the specified format.
+*/
+async function exportDataset(dataset, filePath, format) {
+	const safePath = validateFilePath(filePath);
+	const content = exportDatasetToString(dataset, format);
+	await fs.writeFile(safePath, content, "utf-8");
+}
+/**
+* Imports a dataset from a file in the specified format.
+*/
+async function importDataset(id, name, filePath, format) {
+	switch (format) {
+		case "csv": return importFromCSV(id, name, filePath);
+		case "json": return importFromJSON(id, name, filePath);
+		case "jsonl": return importFromJSONL(id, name, filePath);
+	}
+}
+function generateCSV(dataset) {
+	if (dataset.rows.length === 0) return "";
+	const headers = Object.keys(dataset.rows[0]);
+	const csvLines = [];
+	csvLines.push(headers.map((h) => escapeCSVValue(h)).join(","));
+	for (const row of dataset.rows) {
+		const values = headers.map((header) => {
+			const value = row[header];
+			if (value === null || value === void 0) return escapeCSVValue("");
+			if (typeof value === "object") return escapeCSVValue(JSON.stringify(value));
+			return escapeCSVValue(typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value));
+		});
+		csvLines.push(values.join(","));
+	}
+	return csvLines.join("\n");
+}
+function generateJSONL(dataset) {
+	return dataset.rows.map((row) => JSON.stringify(row)).join("\n");
+}
+function parseJSONContent(id, name, content) {
+	let rows;
+	try {
+		rows = JSON.parse(content);
+	} catch {
+		throw new Error(`Failed to parse JSON dataset '${id}': invalid JSON`);
+	}
+	if (!Array.isArray(rows)) throw new Error(`Failed to parse JSON dataset '${id}': expected an array of rows`);
+	return {
+		id,
+		name,
+		rows
+	};
+}
+function parseJSONLContent(id, name, content) {
+	return {
+		id,
+		name,
+		rows: content.split("\n").filter((line) => line.trim()).map((line, index) => {
+			try {
+				return JSON.parse(line);
+			} catch {
+				throw new Error(`Failed to parse JSONL dataset '${id}' at line ${String(index + 1)}: invalid JSON`);
+			}
+		})
+	};
+}
+function parseCSVContent(id, name, content) {
+	const lines = splitCSVLines(content);
+	if (lines.length === 0) return {
+		id,
+		name,
+		rows: []
+	};
+	const headers = parseCSVLine(lines[0]);
+	const rows = [];
+	for (let i = 1; i < lines.length; i++) {
+		const values = parseCSVLine(lines[i]);
+		const row = {};
+		for (let j = 0; j < headers.length; j++) row[headers[j]] = values[j] ?? "";
+		rows.push(row);
+	}
+	return {
+		id,
+		name,
+		rows
+	};
+}
+/**
+* Split CSV content into lines, respecting quoted values that contain newlines.
+*/
+function splitCSVLines(content) {
+	const lines = [];
+	let currentLine = "";
+	let inQuotes = false;
+	for (let i = 0; i < content.length; i++) {
+		const char = content[i];
+		const nextChar = content[i + 1];
+		if (char === "\"") {
+			currentLine += char;
+			if (inQuotes && nextChar === "\"") {
+				currentLine += nextChar;
+				i++;
+			} else inQuotes = !inQuotes;
+		} else if (char === "\n" && !inQuotes) {
+			if (currentLine.trim()) lines.push(currentLine);
+			currentLine = "";
+		} else currentLine += char;
+	}
+	if (currentLine.trim()) lines.push(currentLine);
+	return lines;
+}
+async function importFromCSV(id, name, filePath) {
+	const safePath = validateFilePath(filePath);
+	return parseCSVContent(id, name, await fs.readFile(safePath, "utf-8"));
+}
+async function importFromJSON(id, name, filePath) {
+	const safePath = validateFilePath(filePath);
+	return parseJSONContent(id, name, await fs.readFile(safePath, "utf-8"));
+}
+async function importFromJSONL(id, name, filePath) {
+	const safePath = validateFilePath(filePath);
+	return parseJSONLContent(id, name, await fs.readFile(safePath, "utf-8"));
+}
+function escapeCSVValue(value) {
+	if (/^[=+\-@\t\r]/.test(value)) value = "'" + value;
+	if (value.includes(",") || value.includes("\"") || value.includes("\n")) return `"${value.replace(/"/g, "\"\"")}"`;
+	return value;
+}
+function parseCSVLine(line) {
+	const result = [];
+	let current = "";
+	let inQuotes = false;
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		const nextChar = line[i + 1];
+		if (char === "\"") if (inQuotes && nextChar === "\"") {
+			current += "\"";
+			i++;
+		} else inQuotes = !inQuotes;
+		else if (char === "," && !inQuotes) {
+			result.push(current);
+			current = "";
+		} else current += char;
+	}
+	result.push(current);
+	return result;
+}
+
+//#endregion
+export { ActionSchema, AdventureSchema, CallbackAdapter, ConsoleAdapter, Engine, InMemoryAdapter, JourneySchema, SynodeContext, SynodeError, SynodeValidationError, TelemetryCollector, buildNotFoundSuggestion, chance, createValidationSummary, defineAction, defineAdventure, defineDataset, defineEventSchema, defineJourney, definePersona, dryRun, exportDataset, exportDatasetToString, fake, formatErrorMessage, generate, generateDataset, generateDelay, generatePersona, importDataset, importDatasetFromString, levenshtein, oneOf, shouldBounce, suggestClosest, validateBounceChance, validateConfig, validateEvent, validateFilePath, validateTimeSpan, weighted };
+//# sourceMappingURL=index.mjs.map