Events & Hooks

// Lifecycle
type JobStarted struct {
    Job       *Job
    Timestamp time.Time
}

type JobCompleted struct {
    Job       *Job
    Duration  time.Duration
    Timestamp time.Time
}

type JobFailed struct {
    Job       *Job
    Error     error
    Timestamp time.Time
}

type JobRetrying struct {
    Job       *Job
    Attempt   int
    Error     error
    NextRunAt time.Time
    Timestamp time.Time
}

// DECLARED BUT NOT CURRENTLY EMITTED — see the note under this block.
type CheckpointSaved struct {
    JobID     UUID
    CallIndex int
    CallType  string  // e.g. "call", "fanout", "phase"
    Timestamp time.Time
}

// Pause / resume
type JobPaused struct {
    Job       *Job
    Mode      PauseMode
    Timestamp time.Time
}

type JobCancelled struct {
    Job       *Job
    Timestamp time.Time
}

type JobResumed struct {
    Job       *Job
    Timestamp time.Time
}

// Emitted when a signal wakes a waiting job (producer fast path or the
// worker's polling backstop). SignalName is best-effort and may be empty
// on backstop/recovery wakes. Durable-timer (Sleep) deadline wakes without
// a pending signal do NOT emit this event.
type JobResumedBySignal struct {
    JobID      UUID
    SignalName string
    Timestamp  time.Time
}

// Emitted when a signal is successfully persisted for a job.
type SignalDelivered struct {
    JobID     UUID
    Name      string
    Timestamp time.Time
}

// Emitted when a worker reclaims a job whose owner is presumed dead, or when a
// worker observes a peer reclaim one of its own in-flight jobs. WorkerID is the
// worker emitting the event; Reason is one of the ReclaimReason* constants:
//
//   - ReclaimReasonStaleLock     ("stale_lock")      — THIS worker's stale-lock
//     reaper recovered a job from a presumed-dead peer. This is the actor side
//     and the true crash leading-indicator ("I recovered N jobs"); alert on it.
//   - ReclaimReasonOwnershipAudit ("ownership_audit") — the ownership audit saw
//     a peer reclaim a job THIS worker was still running. This is the victim
//     side ("a peer took N of my in-flight jobs"), meaning this worker was
//     wrongly presumed dead or stalled.
//
// WARNING: in a multi-process fleet the SAME logical reclaim can surface once
// on the reaper (stale_lock) and once on the victim (ownership_audit), emitted
// by DIFFERENT workers. Keep the two reasons separable and do NOT sum across
// them when counting reclaims.
type JobReclaimed struct {
    JobID     UUID
    WorkerID  string
    Reason    string
    Timestamp time.Time
}

type QueuePaused struct {
    Queue     string
    Timestamp time.Time
}

type QueueResumed struct {
    Queue     string
    Timestamp time.Time
}

type WorkerPaused struct {
    WorkerID  string
    Mode      PauseMode
    Timestamp time.Time
}

type WorkerResumed struct {
    WorkerID  string
    Timestamp time.Time
}

// Ephemeral / custom
type CustomEvent struct {
    JobID     UUID
    Kind      string         // "progress", "phase_change", "log", …
    Data      map[string]any
    Timestamp time.Time
}