@synode/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1142 @@
+import { Faker } from "@faker-js/faker";
+import { z } from "zod";
+
+//#region src/types.d.ts
+
+/**
+ * Represents a generated event.
+ * @see {@link Action} for how events are generated
+ */
+interface Event {
+  id: string;
+  userId: string;
+  sessionId: string;
+  name: string;
+  timestamp: Date;
+  payload: Record<string, unknown>;
+}
+/**
+ * Lifecycle scope for context fields.
+ * Fields with a scope will be automatically cleared when that scope ends.
+ */
+type ContextScope = 'action' | 'adventure' | 'journey';
+/**
+ * Options for setting a context field with TTL/scope.
+ */
+interface ContextSetOptions {
+  /**
+   * Lifecycle scope for this field. When the scope ends, the field is automatically cleared.
+   * - 'action': Field lives only for the duration of the current action
+   * - 'adventure': Field lives for the duration of the current adventure
+   * - 'journey': Field lives for the duration of the current journey
+   */
+  scope?: ContextScope;
+}
+/**
+ * Represents the execution context for a user's journey.
+ * @see {@link SynodeContext} for the implementation
+ */
+interface Context {
+  readonly userId: string;
+  readonly sessionId: string;
+  readonly locale: string;
+  readonly faker: Faker;
+  get<T>(key: string): T | undefined;
+  set<T>(key: string, value: T, options?: ContextSetOptions): void;
+  now(): Date;
+  generateId(prefix?: string): string;
+  hasCompletedJourney(journeyId: string): boolean;
+  markJourneyComplete(journeyId: string): void;
+  dataset(id: string): DatasetHandle;
+  /**
+   * Get a typed dataset handle. Use this with InferDatasetRow for type safety.
+   * @example
+   * ```typescript
+   * const productsDef = defineDataset({ ... });
+   * type Product = InferDatasetRow<typeof productsDef>;
+   * const products = ctx.typedDataset<Product>('products');
+   * const product = products.randomRow(); // typed as Product
+   * ```
+   */
+  typedDataset<TRow extends DatasetRow>(id: string): DatasetHandle<TRow>;
+}
+/**
+ * Handle for querying a dataset from context.
+ */
+interface DatasetHandle<TRow = DatasetRow> {
+  randomRow(): TRow;
+  getRowById(id: string | number): TRow | undefined;
+  getRowByIndex(index: number): TRow | undefined;
+  getAllRows(): TRow[];
+  size(): number;
+}
+/**
+ * Represents a single row in a dataset.
+ */
+type DatasetRow = Record<string, unknown>;
+/**
+ * Represents a generated dataset with metadata and rows.
+ */
+interface Dataset<TRow = DatasetRow> {
+  id: string;
+  name: string;
+  rows: TRow[];
+}
+/**
+ * Field generator with access to row metadata.
+ */
+type DatasetFieldGenerator<T = unknown> = T | ((context: Context, row: {
+  index: number;
+  data: DatasetRow;
+}) => T | Promise<T>);
+/**
+ * Configuration for defining a dataset.
+ * @see {@link InferDatasetRow} for type inference
+ * @see {@link defineDataset} for the builder function
+ */
+interface DatasetDefinition<TFields$1 extends Record<string, unknown> = Record<string, unknown>> {
+  id: string;
+  name: string;
+  count: number;
+  fields: { [K in keyof TFields$1]: TFields$1[K] | ((context: Context, row: {
+    index: number;
+    data: DatasetRow;
+  }) => TFields$1[K] | Promise<TFields$1[K]>) };
+}
+/**
+ * Infer the row type from a dataset definition.
+ * This provides type safety similar to Zod's z.infer.
+ * @see {@link DatasetDefinition} for defining datasets
+ *
+ * @example
+ * ```typescript
+ * const productsDef = defineDataset({
+ *   id: 'products',
+ *   name: 'Products',
+ *   count: 100,
+ *   fields: {
+ *     id: (ctx, row) => `prod-${row.index}`,
+ *     name: (ctx) => ctx.faker.commerce.productName(),
+ *     price: (ctx) => ctx.faker.number.float({ min: 10, max: 500 }),
+ *     category: oneOf(['electronics', 'clothing', 'home']),
+ *   },
+ * });
+ *
+ * // Infer the type
+ * type Product = InferDatasetRow<typeof productsDef>;
+ * // Result: { id: string; name: string; price: number; category: string; }
+ * ```
+ */
+/**
+ * Infers the row type from a dataset definition, unwrapping generator functions and promises.
+ * For each field, if it is a function, uses its return type (unwrapping Promise if needed); otherwise, uses the type as-is.
+ */
+type InferDatasetRow<T> = T extends DatasetDefinition<infer TFields> ? { [K in keyof TFields]: TFields[K] extends ((...args: any[]) => infer R) ? R extends Promise<infer U> ? U : R : TFields[K] } : never;
+/**
+ * Time span configuration for delays.
+ */
+interface TimeSpan {
+  min: number;
+  max: number;
+  distribution?: 'uniform' | 'gaussian' | 'exponential';
+}
+/**
+ * Suppression period after journey completion or bounce.
+ */
+interface SuppressionPeriod {
+  min: number;
+  max: number;
+}
+/**
+ * Represents the configuration for a synthetic data generation journey.
+ * @see {@link Adventure} for session sequences
+ * @see {@link defineJourney} for the builder function
+ */
+interface Journey {
+  id: string;
+  name: string;
+  /**
+   * Journey IDs that must be completed before this journey can start.
+   */
+  requires?: string[];
+  adventures: Adventure[];
+  /**
+   * Chance (0-1) that the journey is never started or completed.
+   */
+  bounceChance?: number;
+  /**
+   * Suppression period after journey completes or bounces.
+   */
+  suppressionPeriod?: SuppressionPeriod;
+}
+/**
+ * Represents a sequence of actions within a journey.
+ * @see {@link Action} for individual behaviors
+ * @see {@link defineAdventure} for the builder function
+ */
+interface Adventure {
+  id: string;
+  name: string;
+  actions: Action[];
+  /**
+   * Time span between actions in this adventure.
+   */
+  timeSpan?: TimeSpan;
+  /**
+   * Chance (0-1) to abandon this adventure.
+   */
+  bounceChance?: number;
+  /**
+   * What to do on bounce: 'stop' ends the journey, 'skip' continues to next adventure.
+   */
+  onBounce?: 'stop' | 'skip';
+}
+/**
+ * Represents a single step or event generator in an adventure.
+ * @see {@link defineAction} for the builder function
+ */
+interface Action {
+  id: string;
+  name: string;
+  /**
+   * Handler must return an array of Events.
+   */
+  handler: (context: Context) => Event[] | Promise<Event[]>;
+  /**
+   * Time span between individual events generated by this action.
+   */
+  timeSpan?: TimeSpan;
+  /**
+   * Chance (0-1) to abandon during this action.
+   */
+  bounceChance?: number;
+}
+/**
+ * Type definition for a field generator.
+ * Can be a static value or a function that returns a value.
+ */
+type FieldGenerator<T = unknown> = T | ((context: Context, payload: Record<string, unknown>) => T | Promise<T>);
+/**
+ * Configuration object for defining an action.
+ * @see {@link Action} for the resolved type
+ */
+interface ActionDefinition {
+  id: string;
+  name: string;
+  /**
+   * Map of field names to their generators.
+   */
+  fields?: Record<string, FieldGenerator>;
+  /**
+   * Custom handler function. If provided, 'fields' is ignored.
+   * Must return an array of Events.
+   */
+  handler?: (context: Context) => Event[] | Promise<Event[]>;
+  /**
+   * Time span between individual events generated by this action.
+   */
+  timeSpan?: TimeSpan;
+  /**
+   * Chance (0-1) to abandon during this action.
+   */
+  bounceChance?: number;
+}
+/**
+ * Validation behavior when an event fails schema validation.
+ * - 'strict': throw on first invalid event
+ * - 'warn': keep the event but record the failure in the summary
+ * - 'skip': drop the event and record the failure in the summary
+ */
+type EventValidationMode = 'strict' | 'warn' | 'skip';
+/**
+ * Configuration for event schema validation.
+ *
+ * @param schema - A single Zod schema applied to all events, or a record mapping
+ *   event names to their individual Zod schemas
+ * @param mode - Validation behavior on failure (default: 'strict')
+ */
+interface EventSchemaConfig {
+  schema: z.ZodType | Record<string, z.ZodType>;
+  mode?: EventValidationMode;
+}
+/**
+ * Interface for output adapters that handle generated events.
+ *
+ * Adapters receive events one at a time during generation and are responsible
+ * for routing them to their final destination (console, file, HTTP, etc.).
+ *
+ * @example
+ * ```ts
+ * const adapter: OutputAdapter = {
+ *   write(event) { console.log(event.name); },
+ *   close() { console.log('done'); },
+ * };
+ * ```
+ */
+interface OutputAdapter {
+  /**
+   * Writes a single event to the output destination.
+   *
+   * @param event - The generated event to write
+   * @returns void or a Promise that resolves when the write completes
+   */
+  write(event: Event): Promise<void> | void;
+  /**
+   * Optional cleanup hook called once after all events have been written.
+   * Use for flushing buffers, closing file handles, or finalizing connections.
+   *
+   * @returns void or a Promise that resolves when cleanup completes
+   */
+  close?(): Promise<void> | void;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error codes for all Synode validation and runtime errors.
+ */
+type ErrorCode = 'INVALID_BOUNCE_CHANCE' | 'INVALID_TIME_SPAN' | 'INVALID_SUPPRESSION_PERIOD' | 'UNKNOWN_JOURNEY_REF' | 'CIRCULAR_DEPENDENCY' | 'DUPLICATE_ID' | 'DATASET_NOT_FOUND' | 'DATASET_EMPTY' | 'HANDLER_ERROR' | 'ADAPTER_WRITE_ERROR' | 'INVALID_HANDLER_RETURN' | 'TYPO_DETECTED' | 'INVALID_DATASET_COUNT';
+/**
+ * Options for constructing a SynodeError.
+ *
+ * @param code - The structured error code identifying the error type
+ * @param message - The human-readable error message
+ * @param path - Hierarchical path segments (journey, adventure, action, step)
+ * @param suggestion - Optional suggestion for fixing the error
+ * @param expected - Optional description of the expected value
+ * @param received - Optional description of the actual value received
+ * @param cause - Optional underlying error that caused this one
+ */
+interface SynodeErrorOptions {
+  code: ErrorCode;
+  message: string;
+  path: string[];
+  suggestion?: string;
+  expected?: string;
+  received?: string;
+  cause?: unknown;
+}
+/**
+ * Formats an error message with a hierarchical path prefix and optional suggestion.
+ *
+ * @param message - The base error message
+ * @param path - Hierarchical path segments labeled Journey/Adventure/Action/Step
+ * @param suggestion - Optional suggestion appended on a new line
+ * @returns The formatted message string
+ */
+declare function formatErrorMessage(message: string, path: string[], suggestion?: string): string;
+/**
+ * Structured error class for all Synode validation and runtime errors.
+ *
+ * @example
+ * ```typescript
+ * throw new SynodeError({
+ *   code: 'INVALID_BOUNCE_CHANCE',
+ *   message: 'Bounce chance must be between 0 and 1',
+ *   path: ['Purchase Flow', 'Checkout', 'Submit Order'],
+ *   expected: 'number between 0 and 1',
+ *   received: '1.5',
+ * });
+ * ```
+ */
+declare class SynodeError extends Error {
+  /** Structured error code identifying the error type. */
+  readonly code: ErrorCode;
+  /** Hierarchical path where the error occurred. */
+  readonly path: string[];
+  /** Optional suggestion for fixing the error. */
+  readonly suggestion: string | undefined;
+  /** The original unformatted error message. */
+  readonly rawMessage: string;
+  /** Optional description of the expected value. */
+  readonly expected: string | undefined;
+  /** Optional description of the actual value received. */
+  readonly received: string | undefined;
+  constructor(options: SynodeErrorOptions);
+  /**
+   * Produces a structured multi-line representation of the error for human-readable output.
+   *
+   * Format:
+   * ```
+   * [ERROR_CODE] rawMessage
+   *   Path: Journey 'x' > Adventure 'y' > Action 'z'
+   *   Expected: what was expected
+   *   Received: what was provided
+   *   Fix: suggestion
+   * ```
+   *
+   * Path is omitted when path is empty. Expected/Received are omitted when not provided.
+   * Fix is omitted when there is no suggestion.
+   *
+   * @returns A formatted string representation of the error.
+   */
+  format(): string;
+}
+/**
+ * Computes the Levenshtein edit distance between two strings using a space-efficient
+ * two-row approach.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns The minimum number of single-character edits (insertions, deletions, substitutions)
+ */
+declare function levenshtein(a: string, b: string): number;
+/**
+ * Finds the closest matching string from a list of candidates using Levenshtein distance.
+ * Returns undefined if no candidate is within the dynamic threshold.
+ *
+ * The threshold is `max(3, floor(maxLen * 0.4))` where maxLen is the longer of the
+ * input and candidate strings.
+ *
+ * @param input - The string to match against candidates
+ * @param candidates - List of valid strings to compare against
+ * @returns The closest matching candidate, or undefined if none is close enough
+ */
+declare function suggestClosest(input: string, candidates: string[]): string | undefined;
+/**
+ * Builds a human-readable suggestion string for a not-found error, including
+ * the closest match (if any) and the full list of available options.
+ *
+ * @param kind - The kind of entity (e.g., "dataset", "journey")
+ * @param requested - The name that was requested but not found
+ * @param available - List of valid names
+ * @returns A suggestion string with "Did you mean..." and/or available options
+ */
+declare function buildNotFoundSuggestion(kind: string, requested: string, available: string[]): string;
+//#endregion
+//#region src/state/ids.d.ts
+/**
+ * Interface for ID generation strategies.
+ */
+interface IdGenerator {
+  generate(prefix?: string): string;
+}
+//#endregion
+//#region src/state/context.d.ts
+declare class SynodeContext implements Context {
+  private idGenerator;
+  readonly locale: string;
+  private state;
+  private fieldMetadata;
+  private currentTime;
+  private _userId;
+  private _sessionId;
+  private _faker;
+  private completedJourneys;
+  private datasets;
+  constructor(startTime?: Date, idGenerator?: IdGenerator, locale?: string);
+  get faker(): Faker;
+  get userId(): string;
+  get sessionId(): string;
+  get<T>(key: string): T | undefined;
+  /**
+   * Set a context field value with optional scope for automatic cleanup.
+   *
+   * @param key - The field name
+   * @param value - The field value
+   * @param options - Optional settings including lifecycle scope
+   *
+   * @remarks
+   * When calling `set()` multiple times on the same field with different scopes,
+   * the most recent scope setting will be used. For example, if a field is first
+   * set with `scope: 'adventure'` and later set again with `scope: 'action'`,
+   * it will be cleared at the end of the action rather than the adventure.
+   *
+   * @example
+   * ```typescript
+   * ctx.set('cartItems', [], { scope: 'adventure' });
+   * // Later in the same adventure...
+   * ctx.set('cartItems', ['item1'], { scope: 'action' }); // Now scoped to action
+   * ```
+   */
+  set<T>(key: string, value: T, options?: ContextSetOptions): void;
+  now(): Date;
+  generateId(prefix?: string): string;
+  hasCompletedJourney(journeyId: string): boolean;
+  markJourneyComplete(journeyId: string): void;
+  dataset(id: string): DatasetHandle;
+  typedDataset<TRow extends DatasetRow>(id: string): DatasetHandle<TRow>;
+  /**
+   * Internal: Register a dataset for use in this context.
+   */
+  registerDataset(dataset: Dataset): void;
+  /**
+   * Internal: Advance the simulation time.
+   */
+  advanceTime(ms: number): void;
+  /**
+   * Internal: Rotate the session ID.
+   */
+  rotateSession(): void;
+  /**
+   * Internal: Clear all fields with the specified scope.
+   * Called by the engine when a scope ends.
+   */
+  clearScope(scope: ContextScope): void;
+}
+//#endregion
+//#region src/generators/builder.d.ts
+/**
+ * Defines a new journey.
+ * @param config The journey configuration.
+ * @returns The configured journey object.
+ * @see {@link Journey}
+ */
+declare function defineJourney(config: Journey): Journey;
+/**
+ * Defines a new adventure.
+ * @param config The adventure configuration.
+ * @returns The configured adventure object.
+ * @see {@link Adventure}
+ */
+declare function defineAdventure(config: Adventure): Adventure;
+/**
+ * Defines a new action.
+ * @param config The action configuration.
+ * @returns The configured action object.
+ * @see {@link Action}
+ * @see {@link ActionDefinition}
+ */
+declare function defineAction(config: ActionDefinition): Action;
+//#endregion
+//#region src/generators/fields.d.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.
+ */
+declare function fake<T>(generator: (faker: Faker) => T): FieldGenerator<T>;
+/**
+ * Returns one of the provided options randomly.
+ */
+declare function oneOf<T>(options: T[]): FieldGenerator<T>;
+/**
+ * Returns true with the given probability (0-1).
+ */
+declare function chance(probability: number): FieldGenerator<boolean>;
+/**
+ * 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)
+ */
+declare function weighted<T extends string>(options: Record<T, number>): FieldGenerator<T>;
+//#endregion
+//#region src/generators/persona.d.ts
+/**
+ * Configuration for a user persona.
+ */
+interface PersonaDefinition {
+  id: string;
+  name: string;
+  /**
+   * Attributes to initialize in the user's context.
+   * Can include 'locale' to set the faker locale.
+   */
+  attributes: Record<string, FieldGenerator>;
+}
+/**
+ * Represents an instantiated persona.
+ */
+interface Persona {
+  id: string;
+  name: string;
+  attributes: Record<string, unknown>;
+}
+/**
+ * Defines a new persona.
+ */
+declare function definePersona(config: PersonaDefinition): PersonaDefinition;
+/**
+ * Generates a concrete persona instance from a definition.
+ * This resolves all dynamic fields and weighted distributions.
+ */
+declare function generatePersona(definition: PersonaDefinition, baseContext: Context): Promise<Persona>;
+//#endregion
+//#region src/generators/dataset.d.ts
+/**
+ * Defines a new dataset with type inference support.
+ *
+ * @example
+ * ```typescript
+ * const products = defineDataset({
+ *   id: 'products',
+ *   name: 'Products',
+ *   count: 100,
+ *   fields: {
+ *     id: (ctx, row) => `prod-${row.index}`,
+ *     name: (ctx) => ctx.faker.commerce.productName(),
+ *     price: (ctx) => ctx.faker.number.float({ min: 10, max: 500 }),
+ *   },
+ * });
+ *
+ * // Type inference works automatically
+ * type Product = InferDatasetRow<typeof products>;
+ * ```
+ */
+declare function defineDataset<TFields$1 extends Record<string, unknown>>(config: DatasetDefinition<TFields$1>): DatasetDefinition<TFields$1>;
+/**
+ * Generates a concrete dataset from a definition.
+ * @param definition The dataset definition.
+ * @param context Context providing access to faker, other datasets, and user data.
+ */
+declare function generateDataset<TFields$1 extends Record<string, unknown>>(definition: DatasetDefinition<TFields$1>, context: Context): Promise<Dataset>;
+//#endregion
+//#region src/execution/engine.d.ts
+declare class Engine {
+  private journey;
+  constructor(journey: Journey);
+  /**
+   * Executes the journey and yields events.
+   * @param context Optional context to use. If not provided, a new one is created.
+   */
+  run(context?: SynodeContext): AsyncGenerator<Event>;
+}
+//#endregion
+//#region src/execution/runner.d.ts
+interface RunOptions {
+  /**
+   * Total number of users to simulate.
+   */
+  users: number;
+  /**
+   * Persona definition to use for generating users.
+   * If provided, context will be initialized with persona attributes.
+   */
+  persona?: PersonaDefinition;
+  /**
+   * Optional dataset definitions to pre-generate before journey execution.
+   * Datasets can be referenced within journey actions using ctx.dataset('id').
+   */
+  datasets?: DatasetDefinition[];
+  /**
+   * Number of parallel lanes to use for generation.
+   * Lanes process users concurrently using async execution.
+   * @default 1
+   */
+  lanes?: number;
+  /**
+   * Output adapter to write events to.
+   * @default ConsoleAdapter
+   */
+  adapter?: OutputAdapter;
+  /**
+   * Enable debug mode with telemetry collection.
+   * When enabled, collects detailed metrics about the generation run.
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * File path to save telemetry data when debug mode is enabled.
+   * @default './telemetry-report.json'
+   */
+  telemetryPath?: string;
+  /**
+   * Pre-loaded datasets to register with each user's context.
+   * Unlike `datasets` (which generates from definitions), these are already populated.
+   * Useful for datasets imported from external sources like BigQuery.
+   */
+  preloadedDatasets?: Dataset[];
+  /**
+   * Start of the date range for user start times.
+   * Must be provided together with endDate.
+   */
+  startDate?: Date;
+  /**
+   * End of the date range for user start times.
+   * Must be provided together with startDate.
+   */
+  endDate?: Date;
+  /**
+   * Event schema validation configuration.
+   * When provided, each event is validated against the schema before adapter.write().
+   */
+  eventSchema?: EventSchemaConfig;
+  /**
+   * Path to a module that exports journey definitions for worker thread parallelism.
+   * When provided, generation runs in worker threads instead of Promise.all lanes.
+   * The module must export: { journeys: Journey[], persona?, datasets?, preloadedDatasets? }
+   */
+  workerModule?: string;
+  /**
+   * Number of worker threads to spawn. Default: number of CPU cores.
+   * Only used when workerModule is set.
+   */
+  workers?: number;
+}
+/**
+ * Generates synthetic data based on the provided journey configuration.
+ */
+declare function generate(journey: Journey | Journey[], options: RunOptions): Promise<void>;
+//#endregion
+//#region src/execution/worker-types.d.ts
+/**
+ * Initialization payload sent to each worker thread via `workerData`.
+ * Contains the module path, user range assignment, and any pre-serialized datasets.
+ */
+interface WorkerInit {
+  /** Absolute path to the user's journey module (TS or JS). */
+  workerModule: string;
+  /** First user index (inclusive) this worker should process. */
+  userStart: number;
+  /** Last user index (exclusive) this worker should process. */
+  userEnd: number;
+  /** ISO 8601 start date for randomizing user start times. */
+  startDate?: string;
+  /** ISO 8601 end date for randomizing user start times. */
+  endDate?: string;
+  /** Pre-generated datasets serialized for structured clone transfer. */
+  serializedDatasets?: SerializedDataset[];
+}
+/**
+ * A dataset serialized for transfer across the structured clone boundary.
+ * Mirrors {@link Dataset} but uses plain objects instead of class instances.
+ */
+interface SerializedDataset {
+  /** Unique dataset identifier. */
+  id: string;
+  /** Human-readable dataset name. */
+  name: string;
+  /** The dataset rows as plain objects. */
+  rows: Record<string, unknown>[];
+}
+/**
+ * Message sent from a worker when it has generated a batch of events for one user.
+ */
+interface WorkerEventBatch {
+  type: 'events';
+  events: Event[];
+}
+/**
+ * Message sent from a worker when it begins processing a new user.
+ */
+interface WorkerUserStarted {
+  type: 'user-started';
+}
+/**
+ * Message sent from a worker when it finishes processing a user.
+ */
+interface WorkerUserCompleted {
+  type: 'user-completed';
+  /** Number of events generated for this user. */
+  eventCount: number;
+}
+/**
+ * Message sent from a worker when an unrecoverable error occurs.
+ */
+interface WorkerErrorMessage {
+  type: 'error';
+  /** Human-readable error message. */
+  message: string;
+  /** Optional stack trace from the original error. */
+  stack?: string;
+}
+/**
+ * Final message sent from a worker when all assigned users have been processed.
+ */
+interface WorkerDone {
+  type: 'done';
+  /** Total events generated across all users in this worker. */
+  totalEvents: number;
+  /** Total users processed by this worker. */
+  totalUsers: number;
+}
+/**
+ * Discriminated union of all messages a worker thread can send to the parent.
+ * Use the `type` field to narrow the message in a switch/if block.
+ */
+type WorkerMessage = WorkerEventBatch | WorkerUserStarted | WorkerUserCompleted | WorkerErrorMessage | WorkerDone;
+//#endregion
+//#region src/monitoring/validation.d.ts
+declare const ActionSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  handler: z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>;
+}, z.core.$strip>;
+declare const AdventureSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  actions: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    handler: z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const JourneySchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  adventures: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    actions: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+      handler: z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 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
+ */
+declare function validateBounceChance(value: number | undefined, path: string[]): void;
+/**
+ * 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
+ */
+declare function validateTimeSpan(timeSpan: TimeSpan | undefined, path: string[]): void;
+/**
+ * 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
+ */
+declare function validateConfig(config: Journey, allJourneys?: Journey[]): void;
+/**
+ * Performs a dry run of the journey for a specified number of users.
+ * Returns all generated events in memory.
+ */
+declare function dryRun(journey: Journey, userCount?: number): Promise<Event[]>;
+//#endregion
+//#region src/monitoring/event-validation.d.ts
+/**
+ * A single validation issue from a failed schema check.
+ */
+interface ValidationIssue {
+  path: (string | number)[];
+  message: string;
+  code: string;
+}
+/**
+ * Options for constructing a SynodeValidationError.
+ */
+interface SynodeValidationErrorOptions {
+  message: string;
+  event: Event;
+  issues: ValidationIssue[];
+}
+/**
+ * Error thrown when an event fails schema validation in strict mode.
+ */
+declare class SynodeValidationError extends Error {
+  readonly event: Event;
+  readonly issues: ValidationIssue[];
+  constructor(options: SynodeValidationErrorOptions);
+}
+/**
+ * Aggregate summary of event validation results.
+ */
+interface ValidationSummary {
+  eventsValidated: number;
+  eventsValid: number;
+  eventsInvalid: number;
+  validationErrors: {
+    eventName: string;
+    path: string;
+    message: string;
+  }[];
+}
+/**
+ * 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(),
+ * });
+ * ```
+ */
+declare function defineEventSchema<T extends z.ZodRawShape>(shape: T): z.ZodObject<T>;
+/**
+ * Creates a fresh zeroed validation summary.
+ *
+ * @returns An empty ValidationSummary ready for accumulation
+ */
+declare function createValidationSummary(): ValidationSummary;
+/**
+ * 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
+ */
+declare function validateEvent(event: Event, config: EventSchemaConfig, summary: ValidationSummary): Event | undefined;
+//#endregion
+//#region src/monitoring/telemetry.d.ts
+/**
+ * Telemetry data point captured every second during generation.
+ */
+interface TelemetrySnapshot {
+  /**
+   * Timestamp of this snapshot in ISO format.
+   */
+  timestamp: string;
+  /**
+   * Elapsed time since generation started in milliseconds.
+   */
+  elapsedMs: number;
+  /**
+   * Number of events generated in this second.
+   */
+  eventsPerSecond: number;
+  /**
+   * Total events generated so far.
+   */
+  totalEvents: number;
+  /**
+   * Number of users currently being processed across all lanes.
+   */
+  activeUsers: number;
+  /**
+   * Number of users completed so far.
+   */
+  completedUsers: number;
+  /**
+   * Number of parallel lanes in use.
+   */
+  lanes: number;
+}
+/**
+ * A single validation error captured during event generation.
+ */
+interface TelemetryValidationError {
+  eventName: string;
+  path: string;
+  message: string;
+}
+/**
+ * Complete telemetry report for a generation run.
+ */
+interface TelemetryReport {
+  /**
+   * When the generation started.
+   */
+  startTime: string;
+  /**
+   * When the generation ended.
+   */
+  endTime: string;
+  /**
+   * Total duration in milliseconds.
+   */
+  durationMs: number;
+  /**
+   * Total number of users processed.
+   */
+  totalUsers: number;
+  /**
+   * Total number of events generated.
+   */
+  totalEvents: number;
+  /**
+   * Number of parallel lanes used.
+   */
+  lanes: number;
+  /**
+   * Average events per second across the entire run.
+   */
+  averageEventsPerSecond: number;
+  /**
+   * Number of users currently active (at report time).
+   */
+  activeUsers: number;
+  /**
+   * Number of users completed (at report time).
+   */
+  completedUsers: number;
+  /**
+   * Total number of events that were validated.
+   */
+  eventsValidated: number;
+  /**
+   * Total number of events that passed validation.
+   */
+  eventsValid: number;
+  /**
+   * Total number of events that failed validation.
+   */
+  eventsInvalid: number;
+  /**
+   * Validation errors collected during the run (capped at 50).
+   */
+  validationErrors: TelemetryValidationError[];
+  /**
+   * Per-second telemetry snapshots.
+   */
+  snapshots: TelemetrySnapshot[];
+}
+/**
+ * Collects telemetry data during generation runs.
+ */
+declare class TelemetryCollector {
+  private startTime;
+  private snapshots;
+  private intervalHandle;
+  private currentSecondEvents;
+  private totalEvents;
+  private activeUsers;
+  private completedUsers;
+  private lanes;
+  private eventsValidated;
+  private eventsValid;
+  private eventsInvalid;
+  private validationErrors;
+  constructor(lanes: number);
+  /**
+   * Start collecting telemetry data every second.
+   */
+  start(): void;
+  /**
+   * Stop collecting telemetry data.
+   */
+  stop(): void;
+  /**
+   * Record that an event was generated.
+   */
+  recordEvent(): void;
+  /**
+   * Record that a user started processing.
+   */
+  recordUserStarted(): void;
+  /**
+   * Record that a user completed processing.
+   */
+  recordUserCompleted(): void;
+  /**
+   * Merge a validation summary from a lane or journey into the collector totals.
+   *
+   * @param summary - Aggregated validation counts and errors to record.
+   */
+  recordValidationSummary(summary: {
+    eventsValidated: number;
+    eventsValid: number;
+    eventsInvalid: number;
+    validationErrors: {
+      eventName: string;
+      path: string;
+      message: string;
+    }[];
+  }): void;
+  /**
+   * Generate the final telemetry report.
+   */
+  getReport(): TelemetryReport;
+  /**
+   * Save the telemetry report to a JSON file.
+   */
+  saveReport(filePath: string): Promise<void>;
+  private captureSnapshot;
+}
+//#endregion
+//#region src/monitoring/timing.d.ts
+/**
+ * Generates a delay in milliseconds based on a time span configuration.
+ */
+declare function generateDelay(timeSpan: TimeSpan): number;
+/**
+ * Checks if a bounce should occur based on probability.
+ */
+declare function shouldBounce(bounceChance?: number): boolean;
+//#endregion
+//#region src/adapters/console.d.ts
+/**
+ * Adapter that writes events to the console as pretty-printed JSON.
+ *
+ * @example
+ * ```ts
+ * await generate(journey, { users: 10, adapter: new ConsoleAdapter() });
+ * ```
+ */
+declare class ConsoleAdapter implements OutputAdapter {
+  /** @inheritdoc */
+  write(event: Event): void;
+}
+//#endregion
+//#region src/adapters/memory.d.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);
+ * ```
+ */
+declare class InMemoryAdapter implements OutputAdapter {
+  readonly events: Event[];
+  /** @inheritdoc */
+  write(event: Event): void;
+  /**
+   * Clears all stored events.
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/adapters/callback.d.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 });
+ * ```
+ */
+declare class CallbackAdapter implements OutputAdapter {
+  private callback;
+  constructor(callback: (event: Event) => void | Promise<void>);
+  /** @inheritdoc */
+  write(event: Event): Promise<void>;
+}
+//#endregion
+//#region src/dataset-io.d.ts
+/**
+ * Export format options.
+ */
+type ExportFormat = 'csv' | 'json' | 'jsonl';
+/**
+ * Exports a dataset to a string in the specified format.
+ */
+declare function exportDatasetToString(dataset: Dataset, format: ExportFormat): string;
+/**
+ * Imports a dataset from a string in the specified format.
+ */
+declare function importDatasetFromString(content: string, format: ExportFormat, id?: string, name?: string): Dataset;
+/**
+ * Validates that a file path does not escape the given base directory.
+ * @throws Error if path traversal is detected.
+ */
+declare function validateFilePath(filePath: string, basePath?: string): string;
+/**
+ * Exports a dataset to a file in the specified format.
+ */
+declare function exportDataset(dataset: Dataset, filePath: string, format: ExportFormat): Promise<void>;
+/**
+ * Imports a dataset from a file in the specified format.
+ */
+declare function importDataset(id: string, name: string, filePath: string, format: ExportFormat): Promise<Dataset>;
+//#endregion
+export { Action, ActionDefinition, ActionSchema, Adventure, AdventureSchema, CallbackAdapter, ConsoleAdapter, Context, ContextScope, ContextSetOptions, Dataset, DatasetDefinition, DatasetFieldGenerator, DatasetHandle, DatasetRow, Engine, ErrorCode, Event, EventSchemaConfig, EventValidationMode, ExportFormat, FieldGenerator, InMemoryAdapter, InferDatasetRow, Journey, JourneySchema, OutputAdapter, Persona, PersonaDefinition, RunOptions, SerializedDataset, SuppressionPeriod, SynodeContext, SynodeError, SynodeErrorOptions, SynodeValidationError, SynodeValidationErrorOptions, TelemetryCollector, TelemetryReport, TelemetrySnapshot, TelemetryValidationError, TimeSpan, ValidationIssue, ValidationSummary, WorkerDone, WorkerErrorMessage, WorkerEventBatch, WorkerInit, WorkerMessage, WorkerUserCompleted, WorkerUserStarted, 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.d.cts.map