pub struct TaskEnvelope {
pub format_version: u32,
pub task_id: String,
pub parent: Option<String>,
pub sender: String,
pub recipient: String,
pub worker_version: Option<String>,
pub input: PayloadRef,
pub output_contract: Option<ArtifactContract>,
pub deadline: Option<DateTime<Utc>>,
pub budget: Option<TaskBudget>,
pub idempotency_key: Option<String>,
pub effect: Effect,
}Expand description
The unit of durable work: one task handed from a sender to a recipient through the queue.
The envelope is everything the scheduler and the recipient need and
nothing they don’t — the input travels as a PayloadRef (inline for
small values, content-addressed above the inline threshold), so the
queue row stays cheap to scan and the envelope composes with the Flight
Recorder’s artifact addressing.
Every field after format_version that was added after v1 carries a
serde default, so envelopes queued by an older client keep deserializing;
the default Effect is the conservative NonIdempotent, meaning an
undeclared task is never silently retried.
Fields§
§format_version: u32Envelope format version; TASK_ENVELOPE_FORMAT_VERSION for
anything written now.
task_id: StringUnique task id, assigned by the sender. Server-side ids are
tenant-namespaced like every other id ({tenant}/…); the envelope
itself is namespace-agnostic.
parent: Option<String>The causal parent: the run event or task that created this one
({run_id}:{seq} or a task id). Task lineage composes with the
journal’s causal chain, so a fan-out of durable tasks is one
connected evidence tree. None for root tasks.
sender: StringWho submitted the task — a run id, a node name, or an agent identity. Used for attribution, quotas, and cancellation scoping.
recipient: StringWho executes the task: a worker pool name (the queue routes by pool) or a specific worker identity for pinned placement.
worker_version: Option<String>Version pin (R0.6 wave 3): the exact worker version string this task
may be dispatched to. A run started against worker version w1
stamps its tasks with w1, so a mid-run deploy never changes
semantics under an in-flight execution — the scheduler keeps handing
the task to w1-advertising workers until it finishes.
The pin is an exact string match, deliberately: semver range
matching (^1.4) makes a claim’s outcome depend on the version
grammar’s rules rather than on what the run actually recorded, and
range resolution belongs to the scheduler’s policy, not to a frozen
wire contract. Ranges are documented future work; None (the
default) means unpinned — any worker may claim the task.
input: PayloadRefThe task input, inline or content-addressed. Small inputs travel inside the queue row; large ones are artifacts the recipient resolves through the journal’s artifact map.
output_contract: Option<ArtifactContract>What the task is expected to produce. None means the result is an
unconstrained JSON value (the common case for node executions).
deadline: Option<DateTime<Utc>>Wall-clock deadline for the whole task, across all attempts. The
scheduler does not re-queue a task whose deadline has passed; the
worker treats an expired deadline as ErrorClass::Cancelled.
budget: Option<TaskBudget>Attempt and timeout budget. None means the queue’s defaults.
idempotency_key: Option<String>The deduplication key for effectively-once execution: the queue
refuses a duplicate submission with an existing key, and the
recipient passes it to the effect it performs. Required for any task
whose effect is Effect::Idempotent — the key is what the
idempotency declaration means at the wire. None is honest only
for Pure / ReadOnly work.
effect: EffectThe declared effect classification of the work this task performs —
the same taxonomy the Flight Recorder journals. Defaults to the
conservative NonIdempotent, so a task that does not declare its
effect is never silently retried; declaring Idempotent (with an
idempotency key) is what unlocks automatic retry.
Implementations§
Source§impl TaskEnvelope
impl TaskEnvelope
Sourcepub fn new(
task_id: impl Into<String>,
sender: impl Into<String>,
recipient: impl Into<String>,
input: PayloadRef,
) -> Self
pub fn new( task_id: impl Into<String>, sender: impl Into<String>, recipient: impl Into<String>, input: PayloadRef, ) -> Self
A minimal envelope: sender, recipient, and input, with every optional
field unset and the effect conservatively Effect::NonIdempotent.
Set the optional fields directly; they are public.