event-catalog.md

Event Catalog And Metadata

Namespaces used by the package:

• LiquidRazor\\ProcessEvents\\Worker\\
• LiquidRazor\\ProcessEvents\\ExternalCall\\
• LiquidRazor\\ProcessEvents\\Metadata\\Worker\\
• LiquidRazor\\ProcessEvents\\Metadata\\ExternalCall\\

Worker Lifecycle Events

Event	Constructor payload	Meaning
WorkerSpawnedEvent	WorkerIdentity	A worker instance has been created and is now present in the runtime.
WorkerStartedEvent	WorkerIdentity	The worker has entered active execution.
WorkerFinishedEvent	WorkerIdentity, WorkerTermination	The worker completed normally.
WorkerCrashedEvent	WorkerIdentity, WorkerCrash	The worker ended abnormally because of a crash or unrecoverable error.

Worker metadata:

• WorkerIdentity Carries the normalized worker id through id().
• WorkerTermination Carries exitCode() and optional summaryMessage().
• WorkerCrash Carries failureClass(), message(), and optional code().

External Call Lifecycle Events

Event	Constructor payload	Meaning
ExternalCallStartedEvent	ExternalCallDescriptor, ExternalCallTiming	An outbound call attempt started.
ExternalCallSucceededEvent	ExternalCallDescriptor, ExternalCallTiming	The call attempt completed successfully from the caller perspective.
ExternalCallFailedEvent	ExternalCallDescriptor, ExternalCallTiming, ExternalCallFailure	The call attempt failed in a non-timeout, non-cancelled way.
ExternalCallRetryRequestedEvent	ExternalCallDescriptor, ExternalCallRetry	A later layer decided another attempt should be made.
ExternalCallRetriedEvent	ExternalCallDescriptor, ExternalCallRetry	A retry attempt was actually initiated.
ExternalCallTimedOutEvent	ExternalCallDescriptor, ExternalCallTiming, ExternalCallTimeout	The call attempt was classified as a timeout.
ExternalCallCancelledEvent	ExternalCallDescriptor, ExternalCallCancellation	The call attempt was intentionally cancelled.

External call metadata:

• CallIdentity Stable logical call identifier exposed through value().
• AttemptNumber Positive per-attempt number exposed through value().
• ExternalCallReference Current attempt reference composed of callIdentity() and attemptNumber().
• ExternalTarget Normalized caller-side target system exposed through system().
• ExternalOperation Normalized caller-side operation name exposed through name().
• ExternalTransport Normalized protocol/transport identity exposed through protocol().
• ExternalCallDescriptor Compact descriptor that groups reference(), target(), operation(), and transport().
• ExternalCallTiming Timing data with startedAt(), optional finishedAt(), and optional durationMilliseconds().
• ExternalCallFailure Failure classification with classification(), message(), and optional code().
• ExternalCallRetry Retry metadata with nextAttemptNumber() and optional reason().
• ExternalCallTimeout Timeout metadata with timeoutMilliseconds() and optional classification().
• ExternalCallCancellation Cancellation metadata with reason() and optional origin().

Logical Call Id Versus Attempt Number

External call modeling is intentionally split in two:

• CallIdentity represents the logical outbound call across the full lifecycle
• AttemptNumber represents one execution attempt within that logical call

ExternalCallReference stores the current attempt. ExternalCallRetry stores the next attempt number. This keeps retry intent/execution distinct while preserving the logical call id across retries.

Usage Examples

Worker completion:

<?php

declare(strict_types=1);

use LiquidRazor\ProcessEvents\Metadata\Worker\WorkerIdentity;
use LiquidRazor\ProcessEvents\Metadata\Worker\WorkerTermination;
use LiquidRazor\ProcessEvents\Worker\WorkerFinishedEvent;

$event = new WorkerFinishedEvent(
    new WorkerIdentity('worker-17'),
    new WorkerTermination(0, 'completed'),
);

External call failure followed by retry request:

<?php

declare(strict_types=1);

use DateTimeImmutable;
use LiquidRazor\ProcessEvents\ExternalCall\ExternalCallFailedEvent;
use LiquidRazor\ProcessEvents\ExternalCall\ExternalCallRetryRequestedEvent;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\AttemptNumber;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\CallIdentity;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalCallDescriptor;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalCallFailure;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalCallReference;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalCallRetry;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalCallTiming;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalOperation;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalTarget;
use LiquidRazor\ProcessEvents\Metadata\ExternalCall\ExternalTransport;

$descriptor = new ExternalCallDescriptor(
    new ExternalCallReference(new CallIdentity('call-42'), new AttemptNumber(1)),
    new ExternalTarget('payments-api'),
    new ExternalOperation('capture'),
    new ExternalTransport('http'),
);

$timing = new ExternalCallTiming(
    new DateTimeImmutable('2026-04-03T10:00:00+00:00'),
    new DateTimeImmutable('2026-04-03T10:00:01+00:00'),
    1000,
);

$failed = new ExternalCallFailedEvent(
    $descriptor,
    $timing,
    new ExternalCallFailure('transport_failure', 'connection dropped', 'ECONNRESET'),
);

$retryRequested = new ExternalCallRetryRequestedEvent(
    $descriptor,
    new ExternalCallRetry(new AttemptNumber(2), 'transient failure'),
);

Related Docs

• README
• Architecture