@gravito/horizon 3.2.1 → 4.0.0

package/README.md

@@ -4,15 +4,32 @@ Enterprise-grade distributed task scheduler for the Gravito framework.
 
 `@gravito/horizon` provides a robust, fluent, and highly configurable system for managing scheduled tasks (Cron jobs) in a distributed environment. It supports multiple locking mechanisms to prevent duplicate execution, node role filtering, retries, and comprehensive monitoring hooks.
 
-## Features
-
-- **Fluent API**: Human-readable syntax for defining task schedules (e.g., `.daily().at('14:00')`).
-- **Distributed Locking**: Prevents duplicate task execution across multiple servers (supports Memory, Cache, and Redis).
-- **Node Role Awareness**: Restrict tasks to specific nodes (e.g., only run on `worker` nodes) or broadcast maintenance tasks to all matching nodes.
-- **Reliability Features**: Built-in support for task timeouts and automatic retries with configurable delays.
-- **Shell Command Support**: Schedule raw shell commands alongside TypeScript callbacks.
-- **Lazy Cron Parsing**: Lightweight `SimpleCronParser` for standard expressions, with `cron-parser` only loaded when complex logic is required.
-- **Comprehensive Hooks**: Lifecycle events for monitoring task success, failure, retries, and scheduler activity.
+## ✨ Features
+
+- 🪐 **Galaxy-Ready Distributed Scheduler**: Native integration with PlanetCore for universal task management across all Satellites.
+- 🕒 **Fluent API**: Human-readable syntax for defining task schedules (e.g., `.daily().at('14:00')`).
+- 🔐 **Distributed Locking**: Prevents duplicate task execution across multiple servers (supports Redis/Plasma and SQL).
+- 🧬 **Node-Role Awareness**: Intelligently restrict tasks to specific nodes (e.g., only run on `worker` nodes) or broadcast maintenance tasks.
+- 🛡️ **Reliability Features**: Built-in support for task timeouts and automatic retries with configurable exponential backoff.
+- 🐚 **Shell Command Support**: Schedule raw shell commands alongside TypeScript callbacks (powered by `@gravito/nova`).
+- 📊 **Monitoring Hooks**: Comprehensive lifecycle events for tracking task success, failure, and execution duration.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Horizon acts as the **Clockwork of Jobs (Temporal Coordinator)**.
+
+- **System Heartbeat**: Triggers recurring maintenance, cleanup, and synchronization tasks that keep the Galaxy running smoothly over time.
+- **Node Coordination**: Ensures that even if you have 100 instances of a Satellite, a "Daily Report" task only runs exactly once per day across the entire cluster.
+- **Background Orchestration**: Works with `@gravito/stream` to initiate long-running background processes at specific intervals.
+
+```mermaid
+graph TD
+    H[Horizon: Scheduler] -->|Time Trigger| L{Distributed Lock}
+    L -- "Win Lock" --> T[Task: Daily Cleanup]
+    L -- "Lose Lock" --> S[Skip Execution]
+    T -->|Call| Sat[Satellite: Admin]
+    T -->|Metrics| Mon[Monitor Orbit]
+```
 
 ## Installation
 
@@ -65,13 +82,22 @@ scheduler.task('daily-cleanup', async () => {
 .dailyAt('02:00')
 .onOneServer() // Distributed lock
 
-// Shell command execution
+// Shell command execution (type-safe via @gravito/nova)
 scheduler.exec('sync-storage', 'aws s3 sync ./local s3://bucket')
   .everyFiveMinutes()
   .onNode('worker')
   .retry(3, 5000) // Retry 3 times with 5s delay
+  .timeout(300000) // 5 minute timeout
 ```
 
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Distributed task scheduler core.
+- [🕒 **Distributed Scheduling**](./doc/DISTRIBUTED_SCHEDULING.md) — **NEW**: Multi-server coordination and locking.
+- [🐚 **Shell Execution**](#shell-execution-with-nova) — Type-safe shell commands via Nova.
+
 ## Scheduling API
 
 ### Frequency Methods
@@ -135,6 +161,39 @@ Poll every minute in a long-running process (ideal for Docker):
 bun run gravito schedule:work
 ```
 
+## Shell Execution with Nova
+
+Horizon uses [@gravito/nova](../nova) for shell command execution, which provides:
+
+- **Type-Safe Execution**: Template literal-based API prevents shell injection
+- **Automatic Escaping**: All command arguments are automatically escaped
+- **Consistent API**: Same Shell API used across Gravito framework
+- **Error Handling**: Comprehensive error capture with stdout/stderr
+
+Example with advanced shell operations:
+
+```typescript
+import { Shell } from '@gravito/nova'
+
+scheduler.task('backup-database', async () => {
+  // Use nova Shell API for custom commands
+  const result = await Shell.run`mysqldump -u ${dbUser} -p${dbPassword} ${dbName}`
+    .nothrow()
+    .run()
+
+  if (result.success) {
+    // Upload backup to S3
+    await Shell.run`aws s3 cp - s3://backups/${Date.now()}.sql`
+      .nothrow()
+      .run()
+  }
+})
+.dailyAt('03:00')
+.onOneServer()
+```
+
+---
+
 ## Monitoring Hooks
 
 Subscribe to hooks via `core.hooks` to build monitoring dashboards or alerts:

package/dist/index.cjs

@@ -1,4 +1,3 @@
-"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -7821,6 +7820,35 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors/HorizonError.ts
+var import_core = require("@gravito/core");
+var HorizonError = class extends import_core.SystemException {
+  constructor(status, code, options = {}) {
+    super(status, code, options);
+    this.name = "HorizonError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var HorizonErrorCodes = {
+  // Scheduling errors
+  CRON_PARSE_ERROR: "horizon.cron_parse_error",
+  SCHEDULE_FAILED: "horizon.schedule_failed",
+  COMMAND_FAILED: "horizon.command_failed",
+  // Validation errors
+  INVALID_TIME_FORMAT: "horizon.invalid_time_format",
+  INVALID_MINUTE: "horizon.invalid_minute",
+  INVALID_DAY_OF_WEEK: "horizon.invalid_day_of_week",
+  INVALID_DAY_OF_MONTH: "horizon.invalid_day_of_month",
+  INVALID_TIMEOUT: "horizon.invalid_timeout",
+  INVALID_RETRY_ATTEMPTS: "horizon.invalid_retry_attempts",
+  INVALID_RETRY_DELAY: "horizon.invalid_retry_delay",
+  INVALID_TIMEZONE: "horizon.invalid_timezone",
+  // Lock errors
+  LOCK_DRIVER_REQUIRED: "horizon.lock_driver_required"
+};
+
 // src/SimpleCronParser.ts
 var SimpleCronParser = class {
   /**
@@ -7840,7 +7868,9 @@ var SimpleCronParser = class {
   static isDue(expression, timezone = "UTC", date = /* @__PURE__ */ new Date()) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5) {
-      throw new Error(`Invalid cron expression: ${expression}`);
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: ${expression}`
+      });
     }
     const targetDate = this.getDateInTimezone(date, timezone);
     const minutes = targetDate.getMinutes();
@@ -7903,11 +7933,16 @@ var SimpleCronParser = class {
     try {
       const tzDate = new Date(date.toLocaleString("en-US", { timeZone: timezone }));
       if (Number.isNaN(tzDate.getTime())) {
-        throw new Error();
+        throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+          message: `Invalid timezone: ${timezone}`
+        });
       }
       return tzDate;
-    } catch {
-      throw new Error(`Invalid timezone: ${timezone}`);
+    } catch (err) {
+      if (err instanceof HorizonError) throw err;
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+        message: `Invalid timezone: ${timezone}`
+      });
     }
   }
 };
@@ -7944,7 +7979,9 @@ var CronParser = class {
       });
       return interval.next().toDate();
     } catch (_err) {
-      throw new Error(`Invalid cron expression: ${expression}`);
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: ${expression}`
+      });
     }
   }
   /**
@@ -8167,7 +8204,9 @@ var LockManager = class {
       this.store = new MemoryLockStore();
     } else if (driver === "cache") {
       if (!context?.cache) {
-        throw new Error("CacheManager is required for cache lock driver");
+        throw new HorizonError(422, HorizonErrorCodes.LOCK_DRIVER_REQUIRED, {
+          message: "CacheManager is required for cache lock driver"
+        });
       }
       this.store = new CacheLockStore(context.cache);
     } else {
@@ -8217,24 +8256,19 @@ var LockManager = class {
 };
 
 // src/process/Process.ts
-var import_core = require("@gravito/core");
+var import_nova = require("@gravito/nova");
 async function runProcess(command) {
-  const runtime = (0, import_core.getRuntimeAdapter)();
-  const proc = runtime.spawn(["sh", "-c", command], {
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout ?? null).text(),
-    new Response(proc.stderr ?? null).text()
-  ]);
-  const exitCode = await proc.exited;
-  return {
-    exitCode,
-    stdout,
-    stderr,
-    success: exitCode === 0
-  };
+  try {
+    const result = await import_nova.Shell.run`bash -c ${command}`.nothrow().run();
+    return result;
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false
+    };
+  }
 }
 var Process = class {
   /**
@@ -8253,28 +8287,38 @@ function parseTime(time) {
   const timePattern = /^([0-2]\d):([0-5]\d)$/;
   const match = time.match(timePattern);
   if (!match) {
-    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_TIME_FORMAT, {
+      message: `Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`
+    });
   }
   const hour = Number.parseInt(match[1], 10);
   const minute = Number.parseInt(match[2], 10);
   if (hour > 23) {
-    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_TIME_FORMAT, {
+      message: `Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`
+    });
   }
   return { hour, minute };
 }
 function validateMinute(minute) {
   if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
-    throw new Error(`Invalid minute: ${minute}. Expected integer 0-59`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_MINUTE, {
+      message: `Invalid minute: ${minute}. Expected integer 0-59`
+    });
   }
 }
 function validateDayOfWeek(dayOfWeek) {
   if (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6) {
-    throw new Error(`Invalid day of week: ${dayOfWeek}. Expected 0-6 (Sunday=0, Saturday=6)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_DAY_OF_WEEK, {
+      message: `Invalid day of week: ${dayOfWeek}. Expected 0-6 (Sunday=0, Saturday=6)`
+    });
   }
 }
 function validateDayOfMonth(dayOfMonth) {
   if (!Number.isInteger(dayOfMonth) || dayOfMonth < 1 || dayOfMonth > 31) {
-    throw new Error(`Invalid day of month: ${dayOfMonth}. Expected 1-31`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_DAY_OF_MONTH, {
+      message: `Invalid day of month: ${dayOfMonth}. Expected 1-31`
+    });
   }
 }
 
@@ -8322,16 +8366,16 @@ var TaskSchedule = class {
   cron(expression) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5) {
-      throw new Error(
-        `Invalid cron expression: "${expression}". Expected 5 parts (minute hour day month weekday), got ${parts.length}.`
-      );
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: "${expression}". Expected 5 parts (minute hour day month weekday), got ${parts.length}.`
+      });
     }
     const pattern = /^[0-9,\-/*?L#A-Za-z]+$/;
     for (let i = 0; i < 5; i++) {
       if (!pattern.test(parts[i])) {
-        throw new Error(
-          `Invalid cron expression: "${expression}". Part ${i + 1} ("${parts[i]}") contains invalid characters.`
-        );
+        throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+          message: `Invalid cron expression: "${expression}". Part ${i + 1} ("${parts[i]}") contains invalid characters.`
+        });
       }
     }
     this.task.expression = expression;
@@ -8479,9 +8523,9 @@ var TaskSchedule = class {
     try {
       (/* @__PURE__ */ new Date()).toLocaleString("en-US", { timeZone: timezone });
     } catch {
-      throw new Error(
-        `Invalid timezone: "${timezone}". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid values.`
-      );
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+        message: `Invalid timezone: "${timezone}". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid values.`
+      });
     }
     this.task.timezone = timezone;
     return this;
@@ -8567,7 +8611,9 @@ var TaskSchedule = class {
    */
   timeout(ms) {
     if (ms <= 0) {
-      throw new Error("Timeout must be a positive number");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEOUT, {
+        message: "Timeout must be a positive number"
+      });
     }
     this.task.timeout = ms;
     return this;
@@ -8582,10 +8628,14 @@ var TaskSchedule = class {
    */
   retry(attempts = 3, delayMs = 1e3) {
     if (attempts < 0) {
-      throw new Error("Retry attempts must be non-negative");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_RETRY_ATTEMPTS, {
+        message: "Retry attempts must be non-negative"
+      });
     }
     if (delayMs < 0) {
-      throw new Error("Retry delay must be non-negative");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_RETRY_DELAY, {
+        message: "Retry delay must be non-negative"
+      });
     }
     this.task.retries = attempts;
     this.task.retryDelay = delayMs;
@@ -8700,7 +8750,9 @@ var SchedulerManager = class {
     const task = new TaskSchedule(name, async () => {
       const result = await Process.run(command);
       if (!result.success) {
-        throw new Error(`Command failed: ${result.stderr || result.stdout}`);
+        throw new HorizonError(500, HorizonErrorCodes.COMMAND_FAILED, {
+          message: `Command failed: ${result.stderr || result.stdout}`
+        });
       }
     });
     task.setCommand(command);
@@ -8805,14 +8857,15 @@ var SchedulerManager = class {
       if (task.background) {
         this.executeTask(task).catch((err) => {
           this.logger?.error(`Background task ${task.name} failed`, err);
-        }).finally(async () => {
-          if (task.preventOverlapping) {
+          return { success: false, timedOut: false };
+        }).then(async (result) => {
+          if (task.preventOverlapping && !result.timedOut) {
             await this.lockManager.release(runningLockKey);
           }
         });
       } else {
-        await this.executeTask(task);
-        if (task.preventOverlapping) {
+        const result = await this.executeTask(task);
+        if (task.preventOverlapping && !result.timedOut) {
           await this.lockManager.release(runningLockKey);
         }
       }
@@ -8877,7 +8930,7 @@ var SchedulerManager = class {
           } catch {
           }
         }
-        return;
+        return { success: true, timedOut: false };
       } catch (err) {
         lastError = err;
         this.logger?.error(`Task ${task.name} failed (attempt ${attempt + 1})`, err);
@@ -8900,6 +8953,10 @@ var SchedulerManager = class {
       } catch {
       }
     }
+    return {
+      success: false,
+      timedOut: lastError?.message.includes("timed out after") ?? false
+    };
   }
 };
 

package/dist/index.d.cts

@@ -674,7 +674,7 @@ declare class SchedulerManager {
      * @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);
+    constructor(lockManager: LockManager, logger?: Logger, hooks?: HookManager, currentNodeRole?: string);
     /**
      * Registers a new callback-based scheduled task.
      *
@@ -844,9 +844,9 @@ interface ProcessResult {
 /**
  * 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.
+ * Leverages the Nova Shell orchestration engine to ensure type-safe,
+ * shell-injection-resistant command execution. Supports pipes, redirects,
+ * and environment variables.
  *
  * @param command - Raw shell command string to execute.
  * @returns Resolves to a detailed `ProcessResult` object.

package/dist/index.d.ts

@@ -674,7 +674,7 @@ declare class SchedulerManager {
      * @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);
+    constructor(lockManager: LockManager, logger?: Logger, hooks?: HookManager, currentNodeRole?: string);
     /**
      * Registers a new callback-based scheduled task.
      *
@@ -844,9 +844,9 @@ interface ProcessResult {
 /**
  * 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.
+ * Leverages the Nova Shell orchestration engine to ensure type-safe,
+ * shell-injection-resistant command execution. Supports pipes, redirects,
+ * and environment variables.
  *
  * @param command - Raw shell command string to execute.
  * @returns Resolves to a detailed `ProcessResult` object.

package/dist/index.js

@@ -1,5 +1,34 @@
 import "./chunk-MCKGQKYU.js";
 
+// src/errors/HorizonError.ts
+import { SystemException } from "@gravito/core";
+var HorizonError = class extends SystemException {
+  constructor(status, code, options = {}) {
+    super(status, code, options);
+    this.name = "HorizonError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var HorizonErrorCodes = {
+  // Scheduling errors
+  CRON_PARSE_ERROR: "horizon.cron_parse_error",
+  SCHEDULE_FAILED: "horizon.schedule_failed",
+  COMMAND_FAILED: "horizon.command_failed",
+  // Validation errors
+  INVALID_TIME_FORMAT: "horizon.invalid_time_format",
+  INVALID_MINUTE: "horizon.invalid_minute",
+  INVALID_DAY_OF_WEEK: "horizon.invalid_day_of_week",
+  INVALID_DAY_OF_MONTH: "horizon.invalid_day_of_month",
+  INVALID_TIMEOUT: "horizon.invalid_timeout",
+  INVALID_RETRY_ATTEMPTS: "horizon.invalid_retry_attempts",
+  INVALID_RETRY_DELAY: "horizon.invalid_retry_delay",
+  INVALID_TIMEZONE: "horizon.invalid_timezone",
+  // Lock errors
+  LOCK_DRIVER_REQUIRED: "horizon.lock_driver_required"
+};
+
 // src/SimpleCronParser.ts
 var SimpleCronParser = class {
   /**
@@ -19,7 +48,9 @@ var SimpleCronParser = class {
   static isDue(expression, timezone = "UTC", date = /* @__PURE__ */ new Date()) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5) {
-      throw new Error(`Invalid cron expression: ${expression}`);
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: ${expression}`
+      });
     }
     const targetDate = this.getDateInTimezone(date, timezone);
     const minutes = targetDate.getMinutes();
@@ -82,11 +113,16 @@ var SimpleCronParser = class {
     try {
       const tzDate = new Date(date.toLocaleString("en-US", { timeZone: timezone }));
       if (Number.isNaN(tzDate.getTime())) {
-        throw new Error();
+        throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+          message: `Invalid timezone: ${timezone}`
+        });
       }
       return tzDate;
-    } catch {
-      throw new Error(`Invalid timezone: ${timezone}`);
+    } catch (err) {
+      if (err instanceof HorizonError) throw err;
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+        message: `Invalid timezone: ${timezone}`
+      });
     }
   }
 };
@@ -123,7 +159,9 @@ var CronParser = class {
       });
       return interval.next().toDate();
     } catch (_err) {
-      throw new Error(`Invalid cron expression: ${expression}`);
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: ${expression}`
+      });
     }
   }
   /**
@@ -346,7 +384,9 @@ var LockManager = class {
       this.store = new MemoryLockStore();
     } else if (driver === "cache") {
       if (!context?.cache) {
-        throw new Error("CacheManager is required for cache lock driver");
+        throw new HorizonError(422, HorizonErrorCodes.LOCK_DRIVER_REQUIRED, {
+          message: "CacheManager is required for cache lock driver"
+        });
       }
       this.store = new CacheLockStore(context.cache);
     } else {
@@ -396,24 +436,19 @@ var LockManager = class {
 };
 
 // src/process/Process.ts
-import { getRuntimeAdapter } from "@gravito/core";
+import { Shell } from "@gravito/nova";
 async function runProcess(command) {
-  const runtime = getRuntimeAdapter();
-  const proc = runtime.spawn(["sh", "-c", command], {
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout ?? null).text(),
-    new Response(proc.stderr ?? null).text()
-  ]);
-  const exitCode = await proc.exited;
-  return {
-    exitCode,
-    stdout,
-    stderr,
-    success: exitCode === 0
-  };
+  try {
+    const result = await Shell.run`bash -c ${command}`.nothrow().run();
+    return result;
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false
+    };
+  }
 }
 var Process = class {
   /**
@@ -432,28 +467,38 @@ function parseTime(time) {
   const timePattern = /^([0-2]\d):([0-5]\d)$/;
   const match = time.match(timePattern);
   if (!match) {
-    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_TIME_FORMAT, {
+      message: `Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`
+    });
   }
   const hour = Number.parseInt(match[1], 10);
   const minute = Number.parseInt(match[2], 10);
   if (hour > 23) {
-    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_TIME_FORMAT, {
+      message: `Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`
+    });
   }
   return { hour, minute };
 }
 function validateMinute(minute) {
   if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
-    throw new Error(`Invalid minute: ${minute}. Expected integer 0-59`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_MINUTE, {
+      message: `Invalid minute: ${minute}. Expected integer 0-59`
+    });
   }
 }
 function validateDayOfWeek(dayOfWeek) {
   if (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6) {
-    throw new Error(`Invalid day of week: ${dayOfWeek}. Expected 0-6 (Sunday=0, Saturday=6)`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_DAY_OF_WEEK, {
+      message: `Invalid day of week: ${dayOfWeek}. Expected 0-6 (Sunday=0, Saturday=6)`
+    });
   }
 }
 function validateDayOfMonth(dayOfMonth) {
   if (!Number.isInteger(dayOfMonth) || dayOfMonth < 1 || dayOfMonth > 31) {
-    throw new Error(`Invalid day of month: ${dayOfMonth}. Expected 1-31`);
+    throw new HorizonError(422, HorizonErrorCodes.INVALID_DAY_OF_MONTH, {
+      message: `Invalid day of month: ${dayOfMonth}. Expected 1-31`
+    });
   }
 }
 
@@ -501,16 +546,16 @@ var TaskSchedule = class {
   cron(expression) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5) {
-      throw new Error(
-        `Invalid cron expression: "${expression}". Expected 5 parts (minute hour day month weekday), got ${parts.length}.`
-      );
+      throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+        message: `Invalid cron expression: "${expression}". Expected 5 parts (minute hour day month weekday), got ${parts.length}.`
+      });
     }
     const pattern = /^[0-9,\-/*?L#A-Za-z]+$/;
     for (let i = 0; i < 5; i++) {
       if (!pattern.test(parts[i])) {
-        throw new Error(
-          `Invalid cron expression: "${expression}". Part ${i + 1} ("${parts[i]}") contains invalid characters.`
-        );
+        throw new HorizonError(422, HorizonErrorCodes.CRON_PARSE_ERROR, {
+          message: `Invalid cron expression: "${expression}". Part ${i + 1} ("${parts[i]}") contains invalid characters.`
+        });
       }
     }
     this.task.expression = expression;
@@ -658,9 +703,9 @@ var TaskSchedule = class {
     try {
       (/* @__PURE__ */ new Date()).toLocaleString("en-US", { timeZone: timezone });
     } catch {
-      throw new Error(
-        `Invalid timezone: "${timezone}". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid values.`
-      );
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEZONE, {
+        message: `Invalid timezone: "${timezone}". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid values.`
+      });
     }
     this.task.timezone = timezone;
     return this;
@@ -746,7 +791,9 @@ var TaskSchedule = class {
    */
   timeout(ms) {
     if (ms <= 0) {
-      throw new Error("Timeout must be a positive number");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_TIMEOUT, {
+        message: "Timeout must be a positive number"
+      });
     }
     this.task.timeout = ms;
     return this;
@@ -761,10 +808,14 @@ var TaskSchedule = class {
    */
   retry(attempts = 3, delayMs = 1e3) {
     if (attempts < 0) {
-      throw new Error("Retry attempts must be non-negative");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_RETRY_ATTEMPTS, {
+        message: "Retry attempts must be non-negative"
+      });
     }
     if (delayMs < 0) {
-      throw new Error("Retry delay must be non-negative");
+      throw new HorizonError(422, HorizonErrorCodes.INVALID_RETRY_DELAY, {
+        message: "Retry delay must be non-negative"
+      });
     }
     this.task.retries = attempts;
     this.task.retryDelay = delayMs;
@@ -879,7 +930,9 @@ var SchedulerManager = class {
     const task = new TaskSchedule(name, async () => {
       const result = await Process.run(command);
       if (!result.success) {
-        throw new Error(`Command failed: ${result.stderr || result.stdout}`);
+        throw new HorizonError(500, HorizonErrorCodes.COMMAND_FAILED, {
+          message: `Command failed: ${result.stderr || result.stdout}`
+        });
       }
     });
     task.setCommand(command);
@@ -984,14 +1037,15 @@ var SchedulerManager = class {
       if (task.background) {
         this.executeTask(task).catch((err) => {
           this.logger?.error(`Background task ${task.name} failed`, err);
-        }).finally(async () => {
-          if (task.preventOverlapping) {
+          return { success: false, timedOut: false };
+        }).then(async (result) => {
+          if (task.preventOverlapping && !result.timedOut) {
             await this.lockManager.release(runningLockKey);
           }
         });
       } else {
-        await this.executeTask(task);
-        if (task.preventOverlapping) {
+        const result = await this.executeTask(task);
+        if (task.preventOverlapping && !result.timedOut) {
           await this.lockManager.release(runningLockKey);
         }
       }
@@ -1056,7 +1110,7 @@ var SchedulerManager = class {
           } catch {
           }
         }
-        return;
+        return { success: true, timedOut: false };
       } catch (err) {
         lastError = err;
         this.logger?.error(`Task ${task.name} failed (attempt ${attempt + 1})`, err);
@@ -1079,6 +1133,10 @@ var SchedulerManager = class {
       } catch {
       }
     }
+    return {
+      success: false,
+      timedOut: lastError?.message.includes("timed out after") ?? false
+    };
   }
 };
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/horizon",
-  "version": "3.2.1",
+  "sideEffects": false,
+  "version": "4.0.0",
   "description": "Distributed task scheduler for Gravito framework",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,6 +21,7 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "lint": "biome lint ./src",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
@@ -37,18 +39,20 @@
   ],
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "@gravito/nova": "^1.0.2"
+  },
   "optionalDependencies": {
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
-    "@gravito/core": "^1.6.1",
-    "@gravito/stasis": "^3.1.1"
+    "@gravito/core": "^3.0.0",
+    "@gravito/stasis": "^4.0.0"
   },
   "devDependencies": {
-    "@gravito/stasis": "^3.1.1",
+    "@gravito/stasis": "workspace:*",
     "bun-types": "latest",
-    "@gravito/core": "^1.6.1",
+    "@gravito/core": "workspace:*",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },