Engine

const engine = new Engine(config: EngineConfig);

interface EngineConfig {
  database: string;               // PostgreSQL connection string
  redis: string;                  // Redis connection string
  scheduler?: {
    tickInterval?: number;        // ms between ticks (default: 1000)
    maxRunsPerTick?: number;      // max runs per tick (default: 500)
    partitionKey?: string;        // for multi-instance deployments
  };
  channels?: {
    email?: EmailChannelConfig;
    voice?: VoiceChannelConfig;
  };
  audit?: {
    retention?: { days: number }; // log retention (default: indefinite)
    archiveTo?: string;           // S3 URI for archived logs
  };
}

const run = await engine.execute(plan: ExecutionPlan, params: {
  contact: Contact;
  variables?: Record<string, unknown>;
  startAt?: number;  // tick to start at (default: current tick)
}): Promise<ExecutionRun>;

const run = await engine.getRun(runId: string): Promise<ExecutionRun>;

await engine.pauseRun(runId: string): Promise<void>;

await engine.resumeRun(runId: string): Promise<void>;

await engine.cancelRun(runId: string, reason: string): Promise<void>;

const result = await engine.replay(runId: string, options?: {
  dryRun?: boolean;  // default: true
}): Promise<ReplayResult>;

interface ReplayResult {
  identical: boolean;
  steps: Array<{
    id: string;
    originalResult: StepResult;
    replayedResult: StepResult;
    identical: boolean;
  }>;
  diffs: Array<{
    step: string;
    field: string;
    expected: unknown;
    actual: unknown;
  }>;
}

const timeline = await engine.getTimeline(runId: string): Promise<TimelineEntry[]>;

await engine.ingestEvent(event: {
  type: string;          // 'email.opened', 'email.replied', etc.
  contactId: string;
  runId?: string;        // optional: associate with specific run
  stepId?: string;       // optional: associate with specific step
  data: Record<string, unknown>;
  occurredAt: Date;
}): Promise<void>;