Events

Two surfaces subscribe to the same lifecycle events. Worker-scoped Worker.Builder.on(...) sees only that worker's own job outcomes; client-scoped flexiq.onEvent(...) sees everything — queue-level events plus every event raised by workers built from the same FlexiQ.

try (FlexiQ flexiq = FlexiQ.builder().sqlite("flexiq.db").open()) {
    flexiq.onEvent(EventName.WORKER_OFFLINE, event -> alertOps(event));
    flexiq.onEvent(EventName.WORKFLOW_FAILED, event -> {
        if (event instanceof WorkflowEvent workflow) {
            alertOps(workflow.runId(), workflow.error());
        }
    });

    try (Worker worker = flexiq.worker()
            .handle(add, payload -> payload.a() + payload.b())
            .on(EventName.SUCCESS, event -> log.info("done " + event.jobId))
            .on(EventName.JOB_FAILED, event -> log.warn("attempt failed: " + event.taskName))
            .on(EventName.DEAD, event -> alertOps(event))
            .start()) {
        worker.awaitShutdown();
    }
}

Worker.Builder.on(EventName, Consumer<OutcomeEvent>) is unchanged — still job-outcome events only (SUCCESS, RETRY, DEAD, CANCELLED, and now JOB_FAILED), delivered as a typed OutcomeEvent with no cast. flexiq.onEvent(EventName, Consumer<FlexiQEvent>) is new: since one subscription surface fans in every event type, its callback receives the sealed FlexiQEvent interface and you narrow it yourself:

flexiq.onEvent(EventName.WORKFLOW_GATE_REACHED, event -> {
    if (event instanceof GateEvent gate) {
        log.info("run {} parked at {}", gate.runId(), gate.nodeName());
    }
});

Both surfaces are add-only. Register worker listeners on the builder before start(); register client listeners right after open() returns (the client must exist first) and before any event-producing work begins, then let them go away with the worker or the client. A listener that throws is caught and logged; it never blocks other listeners.

FlexiQEvent

FlexiQEvent is a sealed interface with one method, EventName name(). OutcomeEvent implements it directly; every other event is a record: EnqueuedEvent(jobId, taskName, queue), WorkerEvent(name, queues), QueueEvent(name, queue), WorkflowEvent(name, runId, workflowName, error), GateEvent(runId, nodeName), NodeCompensationEvent(name, runId, nodeName, error), PredicateEvent(taskName, reason).

EventName.wireName() returns the dotted wire string used by webhooks and the dashboard, e.g. EventName.SUCCESS.wireName() is "job.completed".

Events

Job events

SUCCESS, RETRY, DEAD, and CANCELLED are the original constants and keep working unchanged; JOB_ENQUEUED and JOB_FAILED are new siblings, not replacements.

Every OutcomeEvent carries jobId, taskName, and outcome details: error (null on success/cancel), retryCount (-1 when not applicable), and timedOut (which separates a timeout from other failures). durationMs() reports how long the job ran, as the runtime measured it:

.on(EventName.SUCCESS, event -> metrics.record(event.taskName, event.durationMs()))

It returns null when nothing measured the run — JOB_FAILED firing before a duration exists, or a job the runtime recovered rather than a worker finishing it.

Worker events

Queue events

Workflow events

Terminal, gate, and saga events come from the workflow tracker attached to the worker (Worker.Builder.trackWorkflows()).

Predicate events