@gravito/horizon 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -1,309 +1,664 @@
 import { CacheManager } from '@gravito/stasis';
-import { GravitoOrbit, PlanetCore, ActionCallback, Logger, HookManager } from '@gravito/core';
+import { ActionCallback, Logger, HookManager, GravitoOrbit, PlanetCore } from '@gravito/core';
 
+/**
+ * High-performance cron expression evaluator with LRU caching and fallback support.
+ *
+ * Employs a tiered strategy for cron evaluation:
+ * 1. Cache: O(1) lookup for high-frequency checks.
+ * 2. Simple Parser: Lightweight evaluator for standard expressions.
+ * 3. Advanced Parser: Dynamic import of `cron-parser` for complex expressions.
+ *
+ * @internal
+ */
 declare class CronParser {
+    private static cache;
+    /** Cache duration in milliseconds (1 minute). */
+    private static readonly CACHE_TTL;
+    /** Maximum number of unique expression/timezone combinations to store. */
+    private static readonly MAX_CACHE_SIZE;
     /**
-     * Get the next execution date based on a cron expression.
+     * Calculates the next occurrence of a cron expression.
      *
-     * @param expression - Cron expression
-     * @param timezone - Timezone identifier
-     * @param currentDate - Reference date
+     * Dynamically loads `cron-parser` to minimize initial bundle size and memory footprint.
+     *
+     * @param expression - Valid 5-part cron expression.
+     * @param timezone - Target timezone for evaluation (default: "UTC").
+     * @param currentDate - Reference time to calculate from (default: now).
+     * @returns Resolves to the next execution Date object.
+     * @throws {Error} If the expression format is invalid.
+     *
+     * @example
+     * ```typescript
+     * const next = await CronParser.nextDate('0 0 * * *');
+     * ```
      */
     static nextDate(expression: string, timezone?: string, currentDate?: Date): Promise<Date>;
     /**
-     * Check if the cron expression is due to run at the current time (minute precision).
+     * Determines if a task is due for execution at the specified time.
      *
-     * @param expression - Cron expression
-     * @param timezone - Timezone identifier
-     * @param currentDate - Reference date
+     * Uses minute-precision caching to optimize repeated evaluations within
+     * the same scheduling window. Implements LRU eviction to maintain memory efficiency.
+     *
+     * @param expression - Cron expression to evaluate.
+     * @param timezone - Execution timezone.
+     * @param currentDate - Reference time for the check.
+     * @returns True if the expression matches the reference time.
      */
     static isDue(expression: string, timezone?: string, currentDate?: Date): Promise<boolean>;
+    /**
+     * Internal logic for tiered cron evaluation.
+     *
+     * @param expression - Cron expression.
+     * @param timezone - Target timezone.
+     * @param currentDate - Current time.
+     * @returns Boolean indicating if the task is due.
+     *
+     * @internal
+     */
+    private static computeIsDue;
+    /**
+     * Evicts the oldest entry from the cache when capacity is reached.
+     *
+     * @internal
+     */
+    private static cleanupCache;
+    /**
+     * Purges all entries from the internal cache.
+     * Useful for testing or when global timezone settings change.
+     */
+    static clearCache(): void;
+    /**
+     * Compares two dates with minute precision.
+     *
+     * @internal
+     */
     private static minuteMatches;
 }
 
+/**
+ * Contract for distributed lock storage backends.
+ *
+ * Defines the essential operations required to manage mutual exclusion across
+ * multiple scheduler instances. Implementations must ensure atomicity for
+ * distributed safety.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface LockStore {
     /**
-     * Attempt to acquire a lock
-     * @param key The lock key
-     * @param ttlSeconds Time to live in seconds
-     * @returns true if lock acquired, false if lock already exists
+     * Attempts to acquire a mutex lock for a specific key.
+     *
+     * Must be atomic. If the key is already locked, it should return false
+     * immediately without blocking.
+     *
+     * @param key - The unique lock identifier.
+     * @param ttlSeconds - Expiration duration in seconds to prevent deadlocks.
+     * @returns True if the lock was successfully acquired.
      */
     acquire(key: string, ttlSeconds: number): Promise<boolean>;
     /**
-     * Release a lock
-     * @param key The lock key
+     * Explicitly releases a held lock.
+     *
+     * Should be idempotent; releasing a non-existent lock should not throw.
+     *
+     * @param key - The lock identifier to remove.
      */
     release(key: string): Promise<void>;
     /**
-     * Force acquire a lock (overwrite existing)
-     * @param key The lock key
-     * @param ttlSeconds Time to live in seconds
+     * Forcibly acquires or refreshes a lock, overwriting any existing state.
+     *
+     * @param key - The lock identifier.
+     * @param ttlSeconds - New expiration duration.
      */
     forceAcquire(key: string, ttlSeconds: number): Promise<void>;
     /**
-     * Check if a lock exists
-     * @param key The lock key
+     * Checks if a lock is currently active and not expired.
+     *
+     * @param key - The lock identifier.
+     * @returns True if the lock exists.
      */
     exists(key: string): Promise<boolean>;
 }
 
+/**
+ * Distributed lock implementation backed by Gravito Stasis.
+ *
+ * Leverages the shared cache system (Redis, Memcached, etc.) to provide
+ * atomic locking across multiple application nodes.
+ *
+ * @example
+ * ```typescript
+ * const store = new CacheLockStore(cacheManager);
+ * const locked = await store.acquire('nightly-sync', 600);
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class CacheLockStore implements LockStore {
     private cache;
     private prefix;
+    /**
+     * Initializes the store with a cache manager.
+     *
+     * @param cache - The Stasis cache instance.
+     * @param prefix - Key prefix to avoid collisions in the shared namespace.
+     */
     constructor(cache: CacheManager, prefix?: string);
+    /**
+     * Computes the fully qualified cache key.
+     *
+     * @internal
+     */
     private getKey;
+    /**
+     * Atomic 'add' operation ensures only one node succeeds.
+     *
+     * @param key - Lock key.
+     * @param ttlSeconds - Expiration.
+     */
     acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Removes the lock key from cache.
+     *
+     * @param key - Lock key.
+     */
     release(key: string): Promise<void>;
+    /**
+     * Overwrites the lock key, effectively resetting the TTL.
+     *
+     * @param key - Lock key.
+     * @param ttlSeconds - New expiration.
+     */
     forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Validates if the lock key is present in the cache.
+     *
+     * @param key - Lock key.
+     */
     exists(key: string): Promise<boolean>;
 }
 
+/**
+ * Orchestrator for distributed locks to prevent concurrent task execution.
+ *
+ * Implements a pluggable storage pattern, allowing the scheduler to operate
+ * in both single-node (Memory) and multi-node (Cache/Redis) environments.
+ * Provides a unified interface for safe lock acquisition and release.
+ *
+ * @example
+ * ```typescript
+ * // Production setup with distributed cache
+ * const locks = new LockManager('cache', { cache: cacheManager });
+ *
+ * // Attempt to acquire a mutex lock for 5 minutes
+ * const acquired = await locks.acquire('task:db-backup', 300);
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class LockManager {
     private store;
+    /**
+     * Initializes the manager with a specific storage driver.
+     *
+     * @param driver - Strategy identifier or a custom `LockStore` implementation.
+     * @param context - Dependencies required by certain drivers (e.g., CacheManager).
+     * @throws {Error} If 'cache' driver is selected but no `CacheManager` is provided.
+     */
     constructor(driver: 'memory' | 'cache' | LockStore, context?: {
         cache?: CacheManager;
     });
+    /**
+     * Attempts to acquire a lock. Fails if the key is already locked.
+     *
+     * @param key - Unique identifier for the lock.
+     * @param ttlSeconds - Time-to-live in seconds before the lock expires.
+     * @returns True if the lock was successfully acquired.
+     */
     acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Explicitly releases a held lock.
+     *
+     * @param key - The lock identifier to remove.
+     * @returns Resolves when the lock is deleted.
+     */
     release(key: string): Promise<void>;
+    /**
+     * Forcibly acquires or overwrites an existing lock.
+     *
+     * Used for execution locks where the latest attempt should take precedence
+     * if the previous one is deemed expired.
+     *
+     * @param key - Lock identifier.
+     * @param ttlSeconds - Expiration duration.
+     */
     forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Checks if a specific lock currently exists and is not expired.
+     *
+     * @param key - Lock identifier.
+     * @returns True if the key is locked and active.
+     */
     exists(key: string): Promise<boolean>;
 }
 
+/**
+ * Lightweight, in-memory lock store for local development and single-node deployments.
+ *
+ * Implements the `LockStore` contract using a local `Map`. It does not support
+ * shared state across processes or servers.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryLockStore();
+ * const ok = await store.acquire('local-job', 60);
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class MemoryLockStore implements LockStore {
+    /** Map of lock keys to their expiration timestamps (ms). */
     private locks;
+    /**
+     * Acquires a local lock if the key is not already active.
+     *
+     * @param key - Lock identifier.
+     * @param ttlSeconds - Expiration duration.
+     */
     acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Deletes the lock from local memory.
+     *
+     * @param key - Lock identifier.
+     */
     release(key: string): Promise<void>;
+    /**
+     * Sets or overwrites a local lock.
+     *
+     * @param key - Lock identifier.
+     * @param ttlSeconds - Expiration.
+     */
     forceAcquire(key: string, ttlSeconds: number): Promise<void>;
-    exists(key: string): Promise<boolean>;
-}
-
-declare class OrbitHorizon implements GravitoOrbit {
     /**
-     * Install the Horizon Orbit into PlanetCore.
+     * Checks if a local lock is present and hasn't expired.
      *
-     * @param core - The PlanetCore instance.
+     * Automatically purges expired locks upon checking.
+     *
+     * @param key - Lock identifier.
      */
-    install(core: PlanetCore): void;
-}
-
-interface ProcessResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-    success: boolean;
-}
-declare function runProcess(command: string): Promise<ProcessResult>;
-declare class Process {
-    static run(command: string): Promise<ProcessResult>;
+    exists(key: string): Promise<boolean>;
 }
 
+/**
+ * Represents the configuration and state of a scheduled task.
+ *
+ * Encapsulates all metadata required by the scheduler to evaluate frequency,
+ * manage distributed locking, and execute task logic with reliability controls.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ScheduledTask {
+    /**
+     * Unique identifier for the task.
+     * Used for logging, hook identification, and as part of the lock key.
+     */
     name: string;
+    /**
+     * Standard 5-part cron expression defining execution frequency.
+     * Format: "minute hour day month weekday"
+     */
     expression: string;
+    /**
+     * Timezone identifier for evaluating the cron expression.
+     * @defaultValue "UTC"
+     */
     timezone: string;
+    /**
+     * The asynchronous task logic to be executed.
+     */
     callback: () => void | Promise<void>;
+    /**
+     * Whether to ensure single-point execution across a distributed environment.
+     * When true, uses a time-window lock to prevent multiple servers from running
+     * the same task in the same scheduling window.
+     */
     shouldRunOnOneServer: boolean;
+    /**
+     * Duration in seconds to hold the distributed time-window lock.
+     * @defaultValue 300
+     */
     lockTtl: number;
+    /**
+     * Whether to execute the task in a non-blocking background mode.
+     * If true, the scheduler won't wait for completion before processing the next task.
+     */
     background: boolean;
+    /**
+     * Optional target node role required for execution.
+     * Tasks will only run if the current node matches this role.
+     */
     nodeRole?: string;
+    /**
+     * Raw shell command if the task was created via `scheduler.exec()`.
+     */
     command?: string;
+    /**
+     * Maximum execution time in milliseconds before the task is aborted.
+     * @defaultValue 3600000
+     */
+    timeout?: number;
+    /**
+     * Number of times to retry a failed task.
+     * @defaultValue 0
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds.
+     * @defaultValue 1000
+     */
+    retryDelay?: number;
+    /**
+     * Whether to prevent concurrent executions of the same task.
+     * If true, a new instance won't start if the previous one is still running.
+     */
+    preventOverlapping: boolean;
+    /**
+     * Maximum duration in seconds for the execution lock.
+     * Prevents deadlocks if a task crashes without releasing the lock.
+     * @defaultValue 3600
+     */
+    overlappingExpiresAt: number;
+    /**
+     * Collection of callbacks executed upon successful task completion.
+     */
     onSuccessCallbacks: ActionCallback[];
+    /**
+     * Collection of callbacks executed when the task fails after all retries.
+     */
     onFailureCallbacks: ActionCallback[];
 }
 /**
- * Fluent API for defining task schedules.
+ * Fluent builder for defining and configuring scheduled tasks.
+ *
+ * Provides a human-readable API for setting execution frequency, constraints,
+ * reliability settings, and lifecycle hooks.
  *
  * @example
- * scheduler.task('backup')
- *   .daily()
- *   .at('02:00')
- *   .onOneServer()
+ * ```typescript
+ * scheduler.task('backup-db', async () => {
+ *   await db.backup();
+ * })
+ * .dailyAt('03:00')
+ * .onOneServer()
+ * .withoutOverlapping()
+ * .retry(3, 5000);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class TaskSchedule {
     private task;
     /**
-     * Create a new TaskSchedule instance.
+     * Initializes a new schedule instance with default settings.
      *
-     * @param name - The unique name of the task.
-     * @param callback - The function to execute.
+     * @param name - Unique task name used for identification and locking.
+     * @param callback - Logic to execute on schedule.
      */
     constructor(name: string, callback: () => void | Promise<void>);
     /**
-     * Set a custom cron expression.
+     * Configures a raw 5-part cron expression.
      *
-     * @param expression - Standard cron expression (e.g., "* * * * *")
-     * @returns The TaskSchedule instance.
+     * @param expression - Cron string (e.g., "0 0 * * *").
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If expression format is invalid or contains forbidden characters.
+     *
+     * @example
+     * ```typescript
+     * schedule.cron('0 9-17 * * 1-5'); // 9-5 on weekdays
+     * ```
      */
     cron(expression: string): this;
     /**
-     * Run the task every minute.
+     * Schedules execution every minute.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     everyMinute(): this;
     /**
-     * Run the task every 5 minutes.
+     * Schedules execution every five minutes.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     everyFiveMinutes(): this;
     /**
-     * Run the task every 10 minutes.
+     * Schedules execution every ten minutes.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     everyTenMinutes(): this;
     /**
-     * Run the task every 15 minutes.
+     * Schedules execution every fifteen minutes.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     everyFifteenMinutes(): this;
     /**
-     * Run the task every 30 minutes.
+     * Schedules execution every thirty minutes.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     everyThirtyMinutes(): this;
     /**
-     * Run the task hourly (at minute 0).
+     * Schedules execution hourly at the top of the hour.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     hourly(): this;
     /**
-     * Run the task hourly at a specific minute.
+     * Schedules execution hourly at a specific minute.
      *
-     * @param minute - Minute (0-59)
-     * @returns The TaskSchedule instance.
+     * @param minute - Target minute (0-59).
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If minute is outside 0-59 range.
      */
     hourlyAt(minute: number): this;
     /**
-     * Run the task daily at midnight (00:00).
+     * Schedules execution daily at midnight.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     daily(): this;
     /**
-     * Run the task daily at a specific time.
+     * Schedules execution daily at a specific time.
+     *
+     * @param time - 24-hour time string in "HH:mm" format.
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If time format is invalid or values are out of range.
      *
-     * @param time - Time in "HH:mm" format (24h)
-     * @returns The TaskSchedule instance.
+     * @example
+     * ```typescript
+     * schedule.dailyAt('14:30');
+     * ```
      */
     dailyAt(time: string): this;
     /**
-     * Run the task weekly on Sunday at midnight.
+     * Schedules execution weekly on Sunday at midnight.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     weekly(): this;
     /**
-     * Run the task weekly on a specific day and time.
+     * Schedules execution weekly on a specific day and time.
      *
-     * @param day - Day of week (0-7, 0 or 7 is Sunday)
-     * @param time - Time in "HH:mm" format (default "00:00")
-     * @returns The TaskSchedule instance.
+     * @param day - Day index (0-6, where 0 is Sunday).
+     * @param time - Optional 24-hour time string "HH:mm" (default "00:00").
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If day index or time format is invalid.
+     *
+     * @example
+     * ```typescript
+     * schedule.weeklyOn(1, '09:00'); // Mondays at 9 AM
+     * ```
      */
     weeklyOn(day: number, time?: string): this;
     /**
-     * Run the task monthly on the 1st day at midnight.
+     * Schedules execution monthly on the first day at midnight.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     monthly(): this;
     /**
-     * Run the task monthly on a specific day and time.
+     * Schedules execution monthly on a specific day and time.
      *
-     * @param day - Day of month (1-31)
-     * @param time - Time in "HH:mm" format (default "00:00")
-     * @returns The TaskSchedule instance.
+     * @param day - Day of month (1-31).
+     * @param time - Optional 24-hour time string "HH:mm" (default "00:00").
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If day or time format is invalid.
      */
     monthlyOn(day: number, time?: string): this;
     /**
-     * Set the timezone for the task execution.
+     * Specifies the timezone for evaluating schedule frequency.
      *
-     * @param timezone - Timezone identifier (e.g., "Asia/Taipei", "UTC")
-     * @returns The TaskSchedule instance.
+     * @param timezone - IANA timezone identifier (e.g., "America/New_York").
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If the timezone identifier is not recognized by the system.
      */
     timezone(timezone: string): this;
     /**
-     * Set the time of execution for the current frequency.
-     * Useful when chaining with daily(), weekly(), etc.
+     * Modifies the execution time of the existing frequency.
+     * Typically used after frequency methods like daily() or weekly().
      *
-     * @param time - Time in "HH:mm" format
-     * @returns The TaskSchedule instance.
+     * @param time - 24-hour time string in "HH:mm" format.
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If time format is invalid.
      */
     at(time: string): this;
     /**
-     * Ensure task runs on only one server at a time (Distributed Locking).
-     * Requires a configured LockStore (Cache or Redis).
+     * Enables distributed locking to ensure only one instance runs globally.
+     * Prevents duplicate execution when multiple servers are polling the same schedule.
      *
-     * @param lockTtlSeconds - Time in seconds to hold the lock (default 300)
-     * @returns The TaskSchedule instance.
+     * @param lockTtlSeconds - Duration in seconds to hold the window lock (default 300).
+     * @returns The TaskSchedule instance for chaining.
      */
     onOneServer(lockTtlSeconds?: number): this;
     /**
-     * Alias for onOneServer.
-     * Prevents overlapping executions of the same task.
+     * Prevents a new task instance from starting if the previous one is still running.
+     *
+     * Unlike `onOneServer()` which uses a time-window lock, this uses an execution lock
+     * to handle long-running tasks that might span multiple scheduling intervals.
      *
-     * @param expiresAt - Lock TTL in seconds
-     * @returns The TaskSchedule instance.
+     * @param expiresAt - Max duration in seconds to keep the execution lock (default 3600).
+     * @returns The TaskSchedule instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * // Prevents overlapping if the heavy operation takes > 1 minute
+     * scheduler.task('data-sync', heavySync)
+     *   .everyMinute()
+     *   .withoutOverlapping();
+     * ```
      */
     withoutOverlapping(expiresAt?: number): this;
     /**
-     * Run task in background (do not wait for completion in the loop).
-     * Note: In Node.js non-blocking environment this is largely semantic,
-     * but affects how we handle error catching and lock release.
+     * Executes the task in background mode.
+     * The scheduler will not wait for this task to finish before proceeding to the next.
      *
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      */
     runInBackground(): this;
     /**
-     * Restrict task execution to a specific node role.
+     * Restricts task execution to nodes with a specific role.
      *
-     * @param role - The required node role (e.g., 'api', 'worker')
-     * @returns The TaskSchedule instance.
+     * @param role - Target role identifier (e.g., "worker").
+     * @returns The TaskSchedule instance for chaining.
      */
     onNode(role: string): this;
     /**
-     * Set the command string for exec tasks.
+     * Defines a maximum execution time for the task.
+     *
+     * @param ms - Timeout duration in milliseconds.
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If timeout is not a positive number.
+     */
+    timeout(ms: number): this;
+    /**
+     * Configures automatic retry behavior for failed executions.
+     *
+     * @param attempts - Max number of retries (default 3).
+     * @param delayMs - Wait time between retries in milliseconds (default 1000).
+     * @returns The TaskSchedule instance for chaining.
+     * @throws {Error} If attempts or delay are negative.
+     */
+    retry(attempts?: number, delayMs?: number): this;
+    /**
+     * Sets the shell command for execution-based tasks.
      *
      * @param command - The command string.
-     * @returns The TaskSchedule instance.
+     * @returns The TaskSchedule instance for chaining.
      * @internal
      */
     setCommand(command: string): this;
     /**
-     * Register a callback to run on task success.
+     * Registers a callback to execute upon successful task completion.
      *
-     * @param callback - The callback function.
-     * @returns The TaskSchedule instance.
+     * @param callback - Function to run on success.
+     * @returns The TaskSchedule instance for chaining.
      */
     onSuccess(callback: ActionCallback): this;
     /**
-     * Register a callback to run on task failure.
+     * Registers a callback to execute when the task fails.
      *
-     * @param callback - The callback function.
-     * @returns The TaskSchedule instance.
+     * @param callback - Function to run on failure.
+     * @returns The TaskSchedule instance for chaining.
      */
     onFailure(callback: ActionCallback): this;
     /**
-     * Set a description for the task (useful for listing).
+     * Attaches a human-readable description to the task.
      *
-     * @param _text - The description text.
-     * @returns The TaskSchedule instance.
+     * @param _text - Description text.
+     * @returns The TaskSchedule instance for chaining.
      */
     description(_text: string): this;
     /**
-     * Get the underlying task configuration.
+     * Returns the final task configuration.
      *
-     * @returns The ScheduledTask object.
+     * @returns The constructed ScheduledTask object.
      */
     getTask(): ScheduledTask;
 }
 
 /**
- * Core Scheduler Manager responsible for managing and executing tasks.
+ * Central registry and execution engine for scheduled tasks.
+ *
+ * Orchestrates the lifecycle of scheduled jobs by evaluating frequencies,
+ * managing distributed locks to prevent duplicate execution, and handling
+ * reliability features like retries and timeouts.
+ *
+ * Architecture Principles:
+ * - Distributed Safety: Uses lock keys scoped to minute precision for global deduplication.
+ * - Non-blocking: Executes tasks in parallel using fire-and-forget patterns.
+ * - Observability: Emits granular lifecycle hooks for monitoring and alerting.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new SchedulerManager(lockManager, logger, hooks, 'worker');
+ *
+ * // Define a maintenance task
+ * scheduler.task('daily-cleanup', async () => {
+ *   await db.cleanup();
+ * })
+ * .dailyAt('03:00')
+ * .onOneServer();
+ * ```
+ *
+ * @public
  */
 declare class SchedulerManager {
     lockManager: LockManager;
@@ -311,56 +666,225 @@ declare class SchedulerManager {
     private hooks?;
     private currentNodeRole?;
     private tasks;
+    /**
+     * Initializes the scheduler engine.
+     *
+     * @param lockManager - Backend for distributed locking.
+     * @param logger - Optional logger for operational visibility.
+     * @param hooks - Optional manager for lifecycle event hooks.
+     * @param currentNodeRole - Role identifier for the local node (used for filtering).
+     */
     constructor(lockManager: LockManager, logger?: Logger | undefined, hooks?: HookManager | undefined, currentNodeRole?: string | undefined);
     /**
-     * Define a new scheduled task.
+     * Registers a new callback-based scheduled task.
      *
-     * @param name - Unique name for the task
-     * @param callback - Function to execute
-     * @returns The newly created TaskSchedule.
+     * @param name - Unique task name used for identification and locking.
+     * @param callback - Asynchronous function containing the task logic.
+     * @returns A fluent TaskSchedule instance for further configuration.
+     *
+     * @example
+     * ```typescript
+     * scheduler.task('process-queues', async () => {
+     *   await queue.process();
+     * }).everyMinute();
+     * ```
      */
     task(name: string, callback: () => void | Promise<void>): TaskSchedule;
     /**
-     * Define a new scheduled command execution task.
+     * Registers a shell command as a scheduled task.
+     *
+     * Executes the command via `sh -c` on matching nodes.
+     *
+     * @param name - Unique identifier for the command task.
+     * @param command - Raw shell command string.
+     * @returns A fluent TaskSchedule instance.
+     * @throws {Error} If the shell command returns a non-zero exit code during execution.
      *
-     * @param name - Unique name for the task
-     * @param command - Shell command to execute
-     * @returns The newly created TaskSchedule.
+     * @example
+     * ```typescript
+     * scheduler.exec('log-rotate', 'logrotate /etc/logrotate.conf')
+     *   .daily()
+     *   .onNode('worker');
+     * ```
      */
     exec(name: string, command: string): TaskSchedule;
     /**
-     * Add a pre-configured task schedule object.
+     * Injects a pre-configured TaskSchedule instance into the registry.
      *
-     * @param schedule - The task schedule to add.
+     * @param schedule - Configured task schedule to register.
      */
     add(schedule: TaskSchedule): void;
     /**
-     * Get all registered task definitions.
+     * Exports all registered tasks for external inspection or serialization.
      *
-     * @returns An array of scheduled tasks.
+     * @returns An array of raw task configurations.
      */
     getTasks(): ScheduledTask[];
     /**
-     * Trigger the scheduler to check and run due tasks.
-     * This is typically called every minute by a system cron or worker loop.
+     * Main evaluation loop that triggers tasks due for execution.
      *
-     * @param date - The current reference date (default: now)
-     * @returns A promise that resolves when the scheduler run is complete.
+     * Should be invoked every minute by a system timer (systemd/cron) or daemon.
+     * Performs frequency checks, role filtering, and parallel execution.
+     *
+     * @param date - Reference time for cron evaluation (default: current time).
+     * @returns Resolves when all due tasks have been initiated.
      */
     run(date?: Date): Promise<void>;
     /**
-     * Execute a specific task with locking logic.
+     * Executes an individual task after validating execution constraints.
+     *
+     * Evaluates node roles, overlapping prevention, and distributed time-window locks
+     * before initiating the actual task logic.
+     *
+     * @param task - Target task configuration.
+     * @param date - Reference time used for lock key generation.
      *
-     * @param task - The task to execute.
      * @internal
      */
     runTask(task: ScheduledTask, date?: Date): Promise<void>;
     /**
-     * Execute the task callback and handle hooks.
+     * Internal wrapper for executing task logic with reliability controls.
+     *
+     * Handles timeouts, retries, and emits lifecycle hooks for monitoring.
      *
-     * @param task - The task to execute.
+     * @param task - The scheduled task to execute.
+     * @returns Resolves when the task (and its retries) completes or fails permanently.
+     *
+     * @internal
      */
     private executeTask;
 }
 
+/**
+ * Enterprise task scheduler orbit enabling distributed cron-based job execution.
+ *
+ * Provides the infrastructure for defining scheduled tasks with distributed locking,
+ * preventing duplicate execution across multi-server deployments. Integrates seamlessly
+ * with Gravito's orbit system to expose the scheduler in both the IoC container and
+ * request context.
+ *
+ * Design rationale: Uses pluggable lock backends (memory/cache) to support both
+ * development (single-node) and production (multi-node) environments without code changes.
+ *
+ * @example
+ * Single-node development setup:
+ * ```typescript
+ * await PlanetCore.boot({
+ *   config: {
+ *     scheduler: {
+ *       lock: { driver: 'memory' }
+ *     }
+ *   },
+ *   orbits: [OrbitHorizon]
+ * })
+ * ```
+ *
+ * @example
+ * Multi-node production with distributed locking:
+ * ```typescript
+ * import { OrbitCache } from '@gravito/stasis'
+ *
+ * await PlanetCore.boot({
+ *   config: {
+ *     scheduler: {
+ *       lock: { driver: 'cache' },
+ *       nodeRole: 'worker'
+ *     }
+ *   },
+ *   orbits: [
+ *     OrbitCache,      // Must load before Horizon
+ *     OrbitHorizon
+ *   ]
+ * })
+ * ```
+ *
+ * @public
+ */
+declare class OrbitHorizon implements GravitoOrbit {
+    /**
+     * Integrates the Horizon scheduler into the PlanetCore lifecycle.
+     *
+     * Orchestrates the initialization sequence:
+     * 1. Resolves lock backend (memory or cache-based).
+     * 2. Instantiates SchedulerManager with global dependencies (logger, hooks).
+     * 3. Registers the scheduler in the IoC container for CLI and global access.
+     * 4. Injects the scheduler into the request context via middleware.
+     *
+     * @param core - PlanetCore instance providing configuration and service container.
+     *
+     * @throws {Error} If the cache driver is explicitly requested but `CacheManager` is unavailable.
+     */
+    install(core: PlanetCore): void;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Scheduler manager for task scheduling */
+        scheduler?: SchedulerManager;
+    }
+}
+
+/**
+ * Encapsulates the outcome of a child process execution.
+ *
+ * Provides status codes and captured stream outputs for programmatic inspection.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface ProcessResult {
+    /** numeric exit code returned by the operating system (0 typically denotes success). */
+    exitCode: number;
+    /** Captured UTF-8 encoded text from the standard output stream. */
+    stdout: string;
+    /** Captured UTF-8 encoded text from the standard error stream. */
+    stderr: string;
+    /** Semantic indicator of successful completion (mapped from exitCode === 0). */
+    success: boolean;
+}
+/**
+ * Spawns a shell command and asynchronously captures its full output.
+ *
+ * Leverages the Gravito runtime adapter to ensure compatibility across different
+ * JavaScript runtimes (Bun, Node.js). Executes commands within a shell (`sh -c`)
+ * to support pipes, redirects, and environment variables.
+ *
+ * @param command - Raw shell command string to execute.
+ * @returns Resolves to a detailed `ProcessResult` object.
+ *
+ * @example
+ * ```typescript
+ * const result = await runProcess('ls -lh /var/logs');
+ * if (result.success) {
+ *   processLogs(result.stdout);
+ * }
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare function runProcess(command: string): Promise<ProcessResult>;
+/**
+ * Utility class for managing child process lifecycles.
+ *
+ * Acts as a wrapper for `runProcess` to maintain compatibility with earlier
+ * versions of the framework.
+ *
+ * @example
+ * ```typescript
+ * const { stdout } = await Process.run('bun -v');
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
+declare class Process {
+    /**
+     * Static alias for `runProcess`.
+     *
+     * @param command - Command to execute.
+     * @returns Process outcome.
+     */
+    static run(command: string): Promise<ProcessResult>;
+}
+
 export { CacheLockStore, CronParser, LockManager, type LockStore, MemoryLockStore, OrbitHorizon, Process, type ProcessResult, type ScheduledTask, SchedulerManager, TaskSchedule, runProcess };