Overview

Naven Events turns cron, interval, and one-time schedules into durable events that application workers consume over HTTP. It is designed for work that may take seconds or minutes, including AI agents, trading strategies, data pipelines, and recurring automation.

Use HTTP long polling for reliable task delivery. WebSockets or SSE may be useful for dashboards, but they are not the source of truth for pending work.

Resource model

Project
├── Project API Keys
└── Event Queues
    ├── Schedules
    └── Events

• An Event Queue defines the default lease duration and retry limit.
• A Schedule defines when Naven creates Events and how overlapping runs are handled.
• An Event is one durable unit of work.
• A Lease gives one worker temporary ownership of an Event.

Delivery lifecycle

available → leased → completed
               │
               ├── nack → available or failed
               └── lease expires → claimable again

Claiming an Event does not mark it complete. A worker must:

1. Claim the Event.
2. Persist a unique local run for the Event ID.
3. Extend the lease while work is active.
4. Persist external side effects and results.
5. Acknowledge the Event.

If the worker crashes, the lease expires and another worker can claim the same Event. Delivery is therefore at least once. Consumers must be idempotent.

Schedule types

Cron day-of-week values use SUN through SAT, not numbers. Set either day-of-month or day-of-week to a specific value, but not both.

Overlap policies

For a five-minute trading strategy, a common configuration is:

{
  "overlapPolicy": "latest",
  "maxConcurrency": 1,
  "maxEventAgeSeconds": 300
}

Always use the Event's scheduledAt when selecting market data. Do not derive the strategy window from the worker's actual start time.

Responsibility boundary

Naven owns:

• Schedule reconciliation and durable event creation.
• Claim, lease, heartbeat, acknowledgement, and retry state.
• Event age and overlap enforcement.
• Failed and expired Event replay.

Your application owns:

• Business-level deduplication using the Event ID.
• Long-running AI or strategy execution.
• Idempotent external side effects.
• Trading order reconciliation and deterministic exchange clientOrderId values.

Naven does not promise exactly-once execution of an external side effect.