Platform Execution Model
The platform execution model describes how Hot creates and connects durable execution units. It is distinct from the Language Evaluation Model, which describes how expressions, arguments, flows, and Results behave inside one run or task attempt.
The Lifecycle
Most platform work follows this pattern:
A stream ties the whole chain together. Events, runs, retries, and tasks
carry the same stream ID as work continues. A new externally published event
creates a stream unless the caller supplies an existing stream_id.
Platform Units
Event
An event is a persisted message. The platform routes it to matching handler definitions. One event may select zero, one, or multiple handlers; each selected handler invocation receives its own run attempt.
Events use at-least-once delivery. Redelivery and retries can produce more than one attempt, and events in the same stream are not guaranteed to execute in strict order.
Handler
A handler is a function definition registered for an event type. It is routing metadata, not a separate execution record. The execution of a selected handler is recorded as a run.
Run
A run is one platform-invoked, top-level function execution attempt. API calls, event handlers, schedules, and task workers can create runs.
Ordinary Hot function calls made inside that top-level function do not create additional platform runs. They appear as calls within the current run's execution trace. Publishing an event, starting a task, or retrying work crosses a platform execution boundary and creates a new linked unit.
A retry is a new run attempt linked to its prior run through origin_run_id.
It keeps the same triggering data and stream.
Task
A task is a long-running asynchronous resource started from a run or another task. It inherits the current stream and records the run that started it. Executing the task also creates a task-type run, so its function calls, result, timing, and failures remain observable through the same run model.
Code tasks add messaging and checkpoints. Container tasks run an OCI container. See Tasks for their lifecycles and APIs.
Stream
A stream has two related roles:
- Execution lineage — it correlates the events, runs, retries, and tasks that belong to one workflow or interaction.
- Live delivery — clients can subscribe to run lifecycle notifications and
data emitted with
::hot::stream/data.
Events, runs, and task records are durable. User-emitted stream:data messages
are live delivery payloads and are not persisted as workflow records. A stream
is also not a serialization lock: workers may process related work
concurrently.
Workers
Workers consume queued events and tasks. Event workers route events and execute selected handlers as runs; task workers execute code or container tasks. Worker scaling changes throughput, not the lineage relationships recorded in the stream.
What Creates a New Unit?
| Operation | Platform effect |
|---|---|
| Call a Hot function normally | Stays inside the current run or task trace |
send(...) | Persists a child event in the current stream |
send("hot:call", ...) | Persists an event that dispatches another function as a new run |
::hot::task/start(...) or ::hot::box/start(...) | Creates a task linked to the current run and stream |
| Retry a failed run | Creates a new run linked to the prior attempt |
::hot::stream/data(...) | Publishes ephemeral live data on the current stream |
Persistence and Lineage
| Record | Key relationships |
|---|---|
| Event | event_id, stream_id |
| Run | run_id, event_id, stream_id, optional origin_run_id |
| Task | task_id, stream_id, origin_run_id, associated execution run_id |
| Stream | Correlation ID and aggregate history for the workflow |
For detailed state machines and APIs, continue with Runs, Events & Streams, Tasks, and Durable Execution.