Events¶

EventType ¶

Bases: enum.Enum

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

ASSET_DATA_COMPLETED ¶

ASSET_DATA_COMPLETED = <EventType.ASSET_DATA_COMPLETED: 'asset_data_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

ASSET_DATA_FAILED ¶

ASSET_DATA_FAILED = <EventType.ASSET_DATA_FAILED: 'asset_data_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

ASSET_DATA_STARTED ¶

ASSET_DATA_STARTED = <EventType.ASSET_DATA_STARTED: 'asset_data_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

BACKFILL_COMPLETED ¶

BACKFILL_COMPLETED = <EventType.BACKFILL_COMPLETED: 'backfill_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

BACKFILL_FAILED ¶

BACKFILL_FAILED = <EventType.BACKFILL_FAILED: 'backfill_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

BACKFILL_STARTED ¶

BACKFILL_STARTED = <EventType.BACKFILL_STARTED: 'backfill_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_READ_COMPLETED ¶

DEST_READ_COMPLETED = <EventType.DEST_READ_COMPLETED: 'dest_read_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_READ_FAILED ¶

DEST_READ_FAILED = <EventType.DEST_READ_FAILED: 'dest_read_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_READ_STARTED ¶

DEST_READ_STARTED = <EventType.DEST_READ_STARTED: 'dest_read_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_WRITE_COMPLETED ¶

DEST_WRITE_COMPLETED = <EventType.DEST_WRITE_COMPLETED: 'dest_write_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_WRITE_FAILED ¶

DEST_WRITE_FAILED = <EventType.DEST_WRITE_FAILED: 'dest_write_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

DEST_WRITE_STARTED ¶

DEST_WRITE_STARTED = <EventType.DEST_WRITE_STARTED: 'dest_write_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

HOOK_FAILED ¶

HOOK_FAILED = <EventType.HOOK_FAILED: 'hook_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

HOOK_FIRED ¶

HOOK_FIRED = <EventType.HOOK_FIRED: 'hook_fired'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

LOG ¶

LOG = <EventType.LOG: 'log'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_CANCELED ¶

OPERATION_CANCELED = <EventType.OPERATION_CANCELED: 'operation_canceled'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_COMPLETED ¶

OPERATION_COMPLETED = <EventType.OPERATION_COMPLETED: 'operation_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_FAILED ¶

OPERATION_FAILED = <EventType.OPERATION_FAILED: 'operation_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_QUEUED ¶

OPERATION_QUEUED = <EventType.OPERATION_QUEUED: 'operation_queued'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_RETRIED ¶

OPERATION_RETRIED = <EventType.OPERATION_RETRIED: 'operation_retried'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

OPERATION_STARTED ¶

OPERATION_STARTED = <EventType.OPERATION_STARTED: 'operation_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

RUN_COMPLETED ¶

RUN_COMPLETED = <EventType.RUN_COMPLETED: 'run_completed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

RUN_FAILED ¶

RUN_FAILED = <EventType.RUN_FAILED: 'run_failed'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

RUN_STARTED ¶

RUN_STARTED = <EventType.RUN_STARTED: 'run_started'>

Every framework lifecycle event type.

Each event carries id, type, timestamp and metadata. The metadata noted on a member comes on top of the run-level metadata (run_id, backfill_id, anything the caller passed) that every event inherits:

operation events carry component_id, component_kind, component_key, parent_id, window and message;
asset data events add qualified_key to those;
destination I/O events add destination_key;
failures add error and, when the operation captures tracebacks, traceback.

The backfill and hook types are defined here so every consumer shares one vocabulary, but the platform records them, not the core runners: the backfill store records a backfill's start and verdict, the hook evaluator a hook's firing.

Event ¶

Event(type: EventType, timestamp: datetime = <factory>, metadata: dict[str, Any] = <factory>, id: str = <factory>)

An event emitted during the framework lifecycle.

Carries a stable unique id, a type, a UTC timestamp, and an arbitrary metadata dict. The id is assigned once by the producer and preserved across serialization, so the same logical event can be persisted idempotently even when it is delivered more than once (e.g. re-emitted from a child process's log stream and also written directly).

Supports JSON and dict serialization for forwarding and persistence.

subject ¶

subject

What the event is about: its qualified key, else its component key, else "-".

Returns:

Type	Description
	The key the event names, or `"-"`.

summary ¶

summary

What the event says: its message, else its error, else "-".

Returns:

Type	Description
	The message the event carries, or `"-"`.

from_dict ¶

from_dict(data: dict[str, Any]) -> Event

Deserialize an Event from a dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Flat mapping as produced by `to_dict` — `type` and `timestamp` are required, `event_id` is optional (a fresh id is generated when absent), and every other key becomes metadata.	required

Returns:

Type	Description
`Event`	The deserialized Event instance.

Raises:

Type	Description
`EventError`	If required fields are missing or have invalid values.

from_json ¶

from_json(json_str: str) -> Event

Deserialize an Event from a JSON string.

Parameters:

Name	Type	Description	Default
`json_str`	`str`	JSON object as produced by `to_json`.	required

Returns:

Type	Description
`Event`	The deserialized Event instance.

from_log_line ¶

from_log_line(line: str) -> Event | None

Try to parse an Event from a log line.

An event line is @EVENT:{...}, as StderrEventHandler writes it. Any other line, or one whose JSON is malformed, is not an event and None is returned.

Parameters:

Name	Type	Description	Default
`line`	`str`	A single log line (may include trailing newline).	required

Returns:

Type	Description
`Event \| None`	The parsed Event, or `None` if the line is not an event.

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to a flat dict with event_id, type, timestamp, and metadata.

Returns:

Type	Description
`dict[str, Any]`	Dict with `event_id`, `type` and `timestamp` as top-level
`dict[str, Any]`	keys, plus all metadata entries inlined.

to_json ¶

to_json() -> str

Serialize to a JSON string.

Returns:

Type	Description
`str`	JSON-encoded string of the event.

EventBus ¶

EventBus()

Thread-safe singleton event bus.

Events are enqueued via emit and processed asynchronously by a background daemon thread. Handlers are called in subscription order.

All interaction goes through static methods — the singleton is an implementation detail:

EventBus.subscribe(my_handler)
EventBus.emit(EventType.ASSET_DATA_STARTED)
EventBus.flush()

Initialize handlers, queue, and background worker (runs once).

emit ¶

emit(
    event_type: EventType,
    *,
    metadata: dict[str, Any] | None = None,
) -> None

Emit an event on the global bus.

Parameters:

Name	Type	Description	Default
`event_type`	`EventType`	The type of event to emit.	required
`metadata`	`dict[str, Any] \| None`	Optional key-value pairs attached to the event.	`None`

emit_event ¶

emit_event(event: Event) -> None

Emit an existing Event as-is on the global bus.

Unlike emit, this preserves the event's id and timestamp rather than creating a fresh event. Use it to re-emit an event received from another process (e.g. parsed from a child container's stderr) so its identity survives end-to-end and the event persists idempotently.

Parameters:

Name	Type	Description	Default
`event`	`Event`	The event to enqueue unchanged.	required

flush ¶

flush(timeout: float | None = None) -> bool

Block until all currently queued events have been processed.

Places a sentinel on the queue and waits for the worker to reach it.

Parameters:

Name	Type	Description	Default
`timeout`	`float \| None`	Maximum seconds to wait. `None` waits indefinitely.	`None`

Returns:

Type	Description
`bool`	`True` if the flush completed, `False` on timeout.

shutdown ¶

shutdown() -> None

Drain the queue and stop the background worker.

Safe to call multiple times (idempotent).

subscribe ¶

subscribe(
    handler: Callable[[Event], None],
    event_types: list[EventType] | None = None,
) -> None

Register a handler.

Parameters:

Name	Type	Description	Default
`handler`	`Callable[[Event], None]`	Callable invoked with each matching event.	required
`event_types`	`list[EventType] \| None`	If provided, only events of these types are delivered. `None` means all event types.	`None`

unsubscribe ¶

unsubscribe(handler: Callable[[Event], None]) -> None

Remove a previously registered handler.

Parameters:

Name	Type	Description	Default
`handler`	`Callable[[Event], None]`	Handler to remove.	required