@bratsos/workflow-engine-host-serverless 0.2.12 → 0.3.0

package/dist/index.d.ts

@@ -19,7 +19,7 @@ interface ServerlessHostConfig {
     jobTransport: JobTransport;
     /** Unique worker identifier (e.g. function name, worker name). */
     workerId: string;
-    /** Stale lease threshold in milliseconds (default: 60_000). */
+    /** Stale lease threshold in milliseconds (default: 300_000). */
     staleLeaseThresholdMs?: number;
     /** Max pending runs to claim per maintenance tick (default: 10). */
     maxClaimsPerTick?: number;
@@ -27,6 +27,8 @@ interface ServerlessHostConfig {
     maxSuspendedChecksPerTick?: number;
     /** Max outbox events to flush per tick (default: 100). */
     maxOutboxFlushPerTick?: number;
+    /** Job lease heartbeat interval in milliseconds (default: 60_000). */
+    jobHeartbeatIntervalMs?: number;
 }
 /** Message shape representing a job to execute. Matches DequeueResult fields. */
 interface JobMessage {

package/dist/index.js

@@ -1,3 +1,5 @@
+import { HOST_DEFAULTS, executeJobWithHeartbeat, runMaintenanceTick } from '@bratsos/workflow-engine/kernel';
+
 // src/host.ts
 var ServerlessHostImpl = class {
   kernel;
@@ -7,45 +9,24 @@ var ServerlessHostImpl = class {
   maxClaimsPerTick;
   maxSuspendedChecksPerTick;
   maxOutboxFlushPerTick;
+  jobHeartbeatIntervalMs;
   constructor(config) {
     this.kernel = config.kernel;
     this.jobTransport = config.jobTransport;
     this.workerId = config.workerId;
-    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? 6e4;
-    this.maxClaimsPerTick = config.maxClaimsPerTick ?? 10;
-    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? 10;
-    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? 100;
+    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? HOST_DEFAULTS.staleLeaseThresholdMs;
+    this.maxClaimsPerTick = config.maxClaimsPerTick ?? HOST_DEFAULTS.maxClaimsPerTick;
+    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? HOST_DEFAULTS.maxSuspendedChecksPerTick;
+    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? HOST_DEFAULTS.maxOutboxFlushPerTick;
+    this.jobHeartbeatIntervalMs = config.jobHeartbeatIntervalMs ?? HOST_DEFAULTS.jobHeartbeatIntervalMs;
   }
   async handleJob(msg) {
-    const config = msg.payload.config || {};
-    const result = await this.kernel.dispatch({
-      type: "job.execute",
-      idempotencyKey: `job:${msg.jobId}:attempt:${msg.attempt}`,
-      workflowRunId: msg.workflowRunId,
-      workflowId: msg.workflowId,
-      stageId: msg.stageId,
-      config
+    return executeJobWithHeartbeat(this.kernel, {
+      jobTransport: this.jobTransport,
+      job: msg,
+      jobHeartbeatIntervalMs: this.jobHeartbeatIntervalMs,
+      logPrefix: "[ServerlessHost]"
     });
-    if (result.outcome === "completed") {
-      await this.jobTransport.complete(msg.jobId);
-      await this.kernel.dispatch({
-        type: "run.transition",
-        workflowRunId: msg.workflowRunId
-      });
-      return { outcome: "completed" };
-    }
-    if (result.outcome === "suspended") {
-      const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 6e4);
-      await this.jobTransport.suspend(msg.jobId, nextPollAt);
-      return { outcome: "suspended" };
-    }
-    const canRetry = !result.ghost && msg.attempt < (msg.maxAttempts ?? 3);
-    await this.jobTransport.fail(
-      msg.jobId,
-      result.error ?? "Unknown error",
-      canRetry
-    );
-    return { outcome: "failed", error: result.error };
   }
   async processAvailableJobs(opts) {
     const maxJobs = opts?.maxJobs ?? 1;
@@ -74,70 +55,14 @@ var ServerlessHostImpl = class {
     return { processed, succeeded, failed };
   }
   async runMaintenanceTick() {
-    let claimed = 0;
-    let suspendedChecked = 0;
-    let staleReleased = 0;
-    let eventsFlushed = 0;
-    try {
-      const claimResult = await this.kernel.dispatch({
-        type: "run.claimPending",
-        workerId: this.workerId,
-        maxClaims: this.maxClaimsPerTick
-      });
-      claimed = claimResult.claimed.length;
-    } catch (error) {
-      console.error("[ServerlessHost] run.claimPending error:", error);
-    }
-    try {
-      const pollResult = await this.kernel.dispatch({
-        type: "stage.pollSuspended",
-        maxChecks: this.maxSuspendedChecksPerTick
-      });
-      suspendedChecked = pollResult.checked;
-      for (const workflowRunId of pollResult.resumedWorkflowRunIds) {
-        await this.kernel.dispatch({
-          type: "run.transition",
-          workflowRunId
-        });
-      }
-    } catch (error) {
-      console.error("[ServerlessHost] stage.pollSuspended error:", error);
-    }
-    try {
-      const reapResult = await this.kernel.dispatch({
-        type: "lease.reapStale",
-        staleThresholdMs: this.staleLeaseThresholdMs
-      });
-      staleReleased = reapResult.released;
-    } catch (error) {
-      console.error("[ServerlessHost] lease.reapStale error:", error);
-    }
-    try {
-      const flushResult = await this.kernel.dispatch({
-        type: "outbox.flush",
-        maxEvents: this.maxOutboxFlushPerTick
-      });
-      eventsFlushed = flushResult.published;
-    } catch (error) {
-      console.error("[ServerlessHost] outbox.flush error:", error);
-    }
-    let stuckReaped = 0;
-    try {
-      const reapStuckResult = await this.kernel.dispatch({
-        type: "run.reapStuck",
-        stuckThresholdMs: Math.max(this.staleLeaseThresholdMs * 3, 5 * 6e4)
-      });
-      stuckReaped = reapStuckResult.failed;
-    } catch (error) {
-      console.error("[ServerlessHost] run.reapStuck error:", error);
-    }
-    return {
-      claimed,
-      suspendedChecked,
-      staleReleased,
-      eventsFlushed,
-      stuckReaped
-    };
+    return runMaintenanceTick(this.kernel, {
+      workerId: this.workerId,
+      maxClaimsPerTick: this.maxClaimsPerTick,
+      maxSuspendedChecksPerTick: this.maxSuspendedChecksPerTick,
+      maxOutboxFlushPerTick: this.maxOutboxFlushPerTick,
+      staleLeaseThresholdMs: this.staleLeaseThresholdMs,
+      logPrefix: "[ServerlessHost]"
+    });
   }
 };
 function createServerlessHost(config) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/host.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Serverless Host for Workflow Engine Command Kernel\n *\n * Platform-agnostic host for serverless environments (Cloudflare Workers,\n * AWS Lambda, Vercel Edge, Deno Deploy, etc.). Unlike the Node host, there\n * are no timers, loops, or signal handlers — every method is a single\n * stateless invocation.\n *\n * Consumers wire platform-specific glue (queue ack/retry, waitUntil,\n * cron triggers) around these methods.\n */\n\nimport type { JobTransport, Kernel } from \"@bratsos/workflow-engine/kernel\";\n\n// ============================================================================\n// Public interfaces\n// ============================================================================\n\nexport interface ServerlessHostConfig {\n  /** Kernel instance to dispatch commands to. */\n  kernel: Kernel;\n\n  /** Job transport for complete/suspend/fail lifecycle. */\n  jobTransport: JobTransport;\n\n  /** Unique worker identifier (e.g. function name, worker name). */\n  workerId: string;\n\n  /** Stale lease threshold in milliseconds (default: 60_000). */\n  staleLeaseThresholdMs?: number;\n\n  /** Max pending runs to claim per maintenance tick (default: 10). */\n  maxClaimsPerTick?: number;\n\n  /** Max suspended stages to check per tick (default: 10). */\n  maxSuspendedChecksPerTick?: number;\n\n  /** Max outbox events to flush per tick (default: 100). */\n  maxOutboxFlushPerTick?: number;\n}\n\n/** Message shape representing a job to execute. Matches DequeueResult fields. */\nexport interface JobMessage {\n  jobId: string;\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  attempt: number;\n  maxAttempts?: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface JobResult {\n  outcome: \"completed\" | \"suspended\" | \"failed\";\n  error?: string;\n}\n\nexport interface ProcessJobsResult {\n  processed: number;\n  succeeded: number;\n  failed: number;\n}\n\nexport interface MaintenanceTickResult {\n  claimed: number;\n  suspendedChecked: number;\n  staleReleased: number;\n  eventsFlushed: number;\n  stuckReaped: number;\n}\n\nexport interface ServerlessHost {\n  /** Execute a single pre-dequeued job. Returns outcome so consumer can ack/retry. */\n  handleJob(msg: JobMessage): Promise<JobResult>;\n\n  /**\n   * Dequeue and process jobs from the jobTransport.\n   * Defaults to 1 job per call (safe for edge runtimes with CPU limits).\n   * Pass maxJobs for longer-running environments like Lambda.\n   */\n  processAvailableJobs(opts?: { maxJobs?: number }): Promise<ProcessJobsResult>;\n\n  /** Run one bounded maintenance tick (claim, poll, reap, flush). */\n  runMaintenanceTick(): Promise<MaintenanceTickResult>;\n}\n\n// ============================================================================\n// Implementation\n// ============================================================================\n\nclass ServerlessHostImpl implements ServerlessHost {\n  private readonly kernel: Kernel;\n  private readonly jobTransport: JobTransport;\n  private readonly workerId: string;\n  private readonly staleLeaseThresholdMs: number;\n  private readonly maxClaimsPerTick: number;\n  private readonly maxSuspendedChecksPerTick: number;\n  private readonly maxOutboxFlushPerTick: number;\n\n  constructor(config: ServerlessHostConfig) {\n    this.kernel = config.kernel;\n    this.jobTransport = config.jobTransport;\n    this.workerId = config.workerId;\n    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? 60_000;\n    this.maxClaimsPerTick = config.maxClaimsPerTick ?? 10;\n    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? 10;\n    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? 100;\n  }\n\n  async handleJob(msg: JobMessage): Promise<JobResult> {\n    const config =\n      (msg.payload as { config?: Record<string, unknown> }).config || {};\n\n    const result = await this.kernel.dispatch({\n      type: \"job.execute\",\n      idempotencyKey: `job:${msg.jobId}:attempt:${msg.attempt}`,\n      workflowRunId: msg.workflowRunId,\n      workflowId: msg.workflowId,\n      stageId: msg.stageId,\n      config,\n    });\n\n    if (result.outcome === \"completed\") {\n      await this.jobTransport.complete(msg.jobId);\n      await this.kernel.dispatch({\n        type: \"run.transition\",\n        workflowRunId: msg.workflowRunId,\n      });\n      return { outcome: \"completed\" };\n    }\n\n    if (result.outcome === \"suspended\") {\n      const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 60_000);\n      await this.jobTransport.suspend(msg.jobId, nextPollAt);\n      return { outcome: \"suspended\" };\n    }\n\n    // failed — ghost jobs should never be retried\n    const canRetry = !result.ghost && msg.attempt < (msg.maxAttempts ?? 3);\n    await this.jobTransport.fail(\n      msg.jobId,\n      result.error ?? \"Unknown error\",\n      canRetry,\n    );\n    return { outcome: \"failed\", error: result.error };\n  }\n\n  async processAvailableJobs(opts?: {\n    maxJobs?: number;\n  }): Promise<ProcessJobsResult> {\n    const maxJobs = opts?.maxJobs ?? 1;\n    let processed = 0;\n    let succeeded = 0;\n    let failed = 0;\n\n    while (processed < maxJobs) {\n      const job = await this.jobTransport.dequeue();\n      if (!job) break;\n\n      const result = await this.handleJob({\n        jobId: job.jobId,\n        workflowRunId: job.workflowRunId,\n        workflowId: job.workflowId,\n        stageId: job.stageId,\n        attempt: job.attempt,\n        maxAttempts: job.maxAttempts,\n        payload: job.payload,\n      });\n\n      processed++;\n      if (result.outcome === \"failed\") {\n        failed++;\n      } else {\n        succeeded++;\n      }\n    }\n\n    return { processed, succeeded, failed };\n  }\n\n  async runMaintenanceTick(): Promise<MaintenanceTickResult> {\n    let claimed = 0;\n    let suspendedChecked = 0;\n    let staleReleased = 0;\n    let eventsFlushed = 0;\n\n    // 1. Claim pending runs → enqueue first-stage jobs\n    try {\n      const claimResult = await this.kernel.dispatch({\n        type: \"run.claimPending\",\n        workerId: this.workerId,\n        maxClaims: this.maxClaimsPerTick,\n      });\n      claimed = claimResult.claimed.length;\n    } catch (error) {\n      console.error(\"[ServerlessHost] run.claimPending error:\", error);\n    }\n\n    // 2. Poll suspended stages → resume if ready\n    try {\n      const pollResult = await this.kernel.dispatch({\n        type: \"stage.pollSuspended\",\n        maxChecks: this.maxSuspendedChecksPerTick,\n      });\n      suspendedChecked = pollResult.checked;\n      for (const workflowRunId of pollResult.resumedWorkflowRunIds) {\n        await this.kernel.dispatch({\n          type: \"run.transition\",\n          workflowRunId,\n        });\n      }\n    } catch (error) {\n      console.error(\"[ServerlessHost] stage.pollSuspended error:\", error);\n    }\n\n    // 3. Reap stale leases → release crashed worker locks\n    try {\n      const reapResult = await this.kernel.dispatch({\n        type: \"lease.reapStale\",\n        staleThresholdMs: this.staleLeaseThresholdMs,\n      });\n      staleReleased = reapResult.released;\n    } catch (error) {\n      console.error(\"[ServerlessHost] lease.reapStale error:\", error);\n    }\n\n    // 4. Flush outbox → publish pending events through EventSink\n    try {\n      const flushResult = await this.kernel.dispatch({\n        type: \"outbox.flush\",\n        maxEvents: this.maxOutboxFlushPerTick,\n      });\n      eventsFlushed = flushResult.published;\n    } catch (error) {\n      console.error(\"[ServerlessHost] outbox.flush error:\", error);\n    }\n\n    // 5. Reap stuck runs → fail runs with no activity past threshold\n    let stuckReaped = 0;\n    try {\n      const reapStuckResult = await this.kernel.dispatch({\n        type: \"run.reapStuck\",\n        stuckThresholdMs: Math.max(this.staleLeaseThresholdMs * 3, 5 * 60_000),\n      });\n      stuckReaped = reapStuckResult.failed;\n    } catch (error) {\n      console.error(\"[ServerlessHost] run.reapStuck error:\", error);\n    }\n\n    return {\n      claimed,\n      suspendedChecked,\n      staleReleased,\n      eventsFlushed,\n      stuckReaped,\n    };\n  }\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createServerlessHost(\n  config: ServerlessHostConfig,\n): ServerlessHost {\n  return new ServerlessHostImpl(config);\n}\n"]}
+{"version":3,"sources":["../src/host.ts"],"names":["runMaintenanceTickCommands"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Serverless Host for Workflow Engine Command Kernel\n *\n * Platform-agnostic host for serverless environments (Cloudflare Workers,\n * AWS Lambda, Vercel Edge, Deno Deploy, etc.). Unlike the Node host, there\n * are no timers, loops, or signal handlers — every method is a single\n * stateless invocation.\n *\n * Consumers wire platform-specific glue (queue ack/retry, waitUntil,\n * cron triggers) around these methods.\n */\n\nimport {\n  executeJobWithHeartbeat,\n  HOST_DEFAULTS,\n  type JobTransport,\n  type Kernel,\n  runMaintenanceTick as runMaintenanceTickCommands,\n} from \"@bratsos/workflow-engine/kernel\";\n\n// ============================================================================\n// Public interfaces\n// ============================================================================\n\nexport interface ServerlessHostConfig {\n  /** Kernel instance to dispatch commands to. */\n  kernel: Kernel;\n\n  /** Job transport for complete/suspend/fail lifecycle. */\n  jobTransport: JobTransport;\n\n  /** Unique worker identifier (e.g. function name, worker name). */\n  workerId: string;\n\n  /** Stale lease threshold in milliseconds (default: 300_000). */\n  staleLeaseThresholdMs?: number;\n\n  /** Max pending runs to claim per maintenance tick (default: 10). */\n  maxClaimsPerTick?: number;\n\n  /** Max suspended stages to check per tick (default: 10). */\n  maxSuspendedChecksPerTick?: number;\n\n  /** Max outbox events to flush per tick (default: 100). */\n  maxOutboxFlushPerTick?: number;\n\n  /** Job lease heartbeat interval in milliseconds (default: 60_000). */\n  jobHeartbeatIntervalMs?: number;\n}\n\n/** Message shape representing a job to execute. Matches DequeueResult fields. */\nexport interface JobMessage {\n  jobId: string;\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  attempt: number;\n  maxAttempts?: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface JobResult {\n  outcome: \"completed\" | \"suspended\" | \"failed\";\n  error?: string;\n}\n\nexport interface ProcessJobsResult {\n  processed: number;\n  succeeded: number;\n  failed: number;\n}\n\nexport interface MaintenanceTickResult {\n  claimed: number;\n  suspendedChecked: number;\n  staleReleased: number;\n  eventsFlushed: number;\n  stuckReaped: number;\n}\n\nexport interface ServerlessHost {\n  /** Execute a single pre-dequeued job. Returns outcome so consumer can ack/retry. */\n  handleJob(msg: JobMessage): Promise<JobResult>;\n\n  /**\n   * Dequeue and process jobs from the jobTransport.\n   * Defaults to 1 job per call (safe for edge runtimes with CPU limits).\n   * Pass maxJobs for longer-running environments like Lambda.\n   */\n  processAvailableJobs(opts?: { maxJobs?: number }): Promise<ProcessJobsResult>;\n\n  /** Run one bounded maintenance tick (claim, poll, reap, flush). */\n  runMaintenanceTick(): Promise<MaintenanceTickResult>;\n}\n\n// ============================================================================\n// Implementation\n// ============================================================================\n\nclass ServerlessHostImpl implements ServerlessHost {\n  private readonly kernel: Kernel;\n  private readonly jobTransport: JobTransport;\n  private readonly workerId: string;\n  private readonly staleLeaseThresholdMs: number;\n  private readonly maxClaimsPerTick: number;\n  private readonly maxSuspendedChecksPerTick: number;\n  private readonly maxOutboxFlushPerTick: number;\n  private readonly jobHeartbeatIntervalMs: number;\n\n  constructor(config: ServerlessHostConfig) {\n    this.kernel = config.kernel;\n    this.jobTransport = config.jobTransport;\n    this.workerId = config.workerId;\n    this.staleLeaseThresholdMs =\n      config.staleLeaseThresholdMs ?? HOST_DEFAULTS.staleLeaseThresholdMs;\n    this.maxClaimsPerTick =\n      config.maxClaimsPerTick ?? HOST_DEFAULTS.maxClaimsPerTick;\n    this.maxSuspendedChecksPerTick =\n      config.maxSuspendedChecksPerTick ??\n      HOST_DEFAULTS.maxSuspendedChecksPerTick;\n    this.maxOutboxFlushPerTick =\n      config.maxOutboxFlushPerTick ?? HOST_DEFAULTS.maxOutboxFlushPerTick;\n    this.jobHeartbeatIntervalMs =\n      config.jobHeartbeatIntervalMs ?? HOST_DEFAULTS.jobHeartbeatIntervalMs;\n  }\n\n  async handleJob(msg: JobMessage): Promise<JobResult> {\n    // Dispatch job.execute under a lease heartbeat and route the outcome\n    // (complete/suspend/fail + terminal run.transition) — see\n    // executeJobWithHeartbeat in @bratsos/workflow-engine/kernel for the\n    // shared command sequence.\n    return executeJobWithHeartbeat(this.kernel, {\n      jobTransport: this.jobTransport,\n      job: msg,\n      jobHeartbeatIntervalMs: this.jobHeartbeatIntervalMs,\n      logPrefix: \"[ServerlessHost]\",\n    });\n  }\n\n  async processAvailableJobs(opts?: {\n    maxJobs?: number;\n  }): Promise<ProcessJobsResult> {\n    const maxJobs = opts?.maxJobs ?? 1;\n    let processed = 0;\n    let succeeded = 0;\n    let failed = 0;\n\n    while (processed < maxJobs) {\n      const job = await this.jobTransport.dequeue();\n      if (!job) break;\n\n      const result = await this.handleJob({\n        jobId: job.jobId,\n        workflowRunId: job.workflowRunId,\n        workflowId: job.workflowId,\n        stageId: job.stageId,\n        attempt: job.attempt,\n        maxAttempts: job.maxAttempts,\n        payload: job.payload,\n      });\n\n      processed++;\n      if (result.outcome === \"failed\") {\n        failed++;\n      } else {\n        succeeded++;\n      }\n    }\n\n    return { processed, succeeded, failed };\n  }\n\n  async runMaintenanceTick(): Promise<MaintenanceTickResult> {\n    // Claim pending runs, poll suspended stages, reap stale leases, flush\n    // the outbox, and reap stuck runs — see runMaintenanceTick in\n    // @bratsos/workflow-engine/kernel for the shared command sequence. The\n    // serverless host returns the per-command counts to its caller (unlike\n    // the Node host, which fires this on a timer and ignores them).\n    return runMaintenanceTickCommands(this.kernel, {\n      workerId: this.workerId,\n      maxClaimsPerTick: this.maxClaimsPerTick,\n      maxSuspendedChecksPerTick: this.maxSuspendedChecksPerTick,\n      maxOutboxFlushPerTick: this.maxOutboxFlushPerTick,\n      staleLeaseThresholdMs: this.staleLeaseThresholdMs,\n      logPrefix: \"[ServerlessHost]\",\n    });\n  }\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createServerlessHost(\n  config: ServerlessHostConfig,\n): ServerlessHost {\n  return new ServerlessHostImpl(config);\n}\n"]}

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@bratsos/workflow-engine-host-serverless",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "Platform-agnostic serverless host for @bratsos/workflow-engine command kernel",
   "type": "module",
   "license": "MIT",
   "author": "Alex Bratsos",
   "repository": {
     "type": "git",
-    "url": "https://github.com/bratsos/workflow-engine",
+    "url": "git+https://github.com/bratsos/workflow-engine.git",
     "directory": "packages/workflow-engine-host-serverless"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
@@ -22,11 +23,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "sideEffects": false,
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@bratsos/workflow-engine": "0.8.0"
+    "@bratsos/workflow-engine": "0.11.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
@@ -34,6 +36,9 @@
     "vitest": "^3.2.4",
     "zod": "^4.1.12"
   },
+  "engines": {
+    "node": ">=22.11.0"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",