Skip to content

Serialized Job Envelope

Message artifact — instantiates Definition-Time Context Binding

Wraps a unit of deferred work together with the minimum context it needs into one self-contained, serializable message, so any worker that picks it up later reconstitutes the intended execution context instead of its own.

A serialized job envelope packages a task — what to do plus the context it must do it in — into a form that can be written to a queue, stored, shipped to another machine, and picked up minutes or days later. It exists because the worker that eventually runs the job is not the one that defined it: without the envelope, the job would resolve names, config, and identity against the worker's ambient environment. Its defining move is the serialization-and-rehydration contract — it fixes what may be put in (values and stable references, never live in-memory objects) and makes the receiving worker validate and reconstitute that context before executing, rather than trusting whatever it happens to deserialize. It also governs the job's lifetime in transit: how long it may wait, and when a stale or undeliverable job is discarded rather than run.

Example

"Send invoice #4471" is enqueued when a subscription renews. The envelope carries the tenant id, the customer's locale, the invoice-template version, the amount, and a handle to the payment-provider secret — not the secret itself. Twenty minutes later a worker on a different host dequeues it.

Before sending, the worker's rehydration gate checks that the template version still exists and the tenant is still active, resolves the secret handle through the vault, and only then renders and sends — in the tenant's locale, not the worker's default. Had the job instead sat in the queue past its 24-hour time-to-live during an outage, it would be dead-lettered rather than sent late against prices that may have changed. The envelope is what makes "run later, elsewhere, by another worker" resolve to the context the renewal was defined under.

How it works

  • Define the wire contract. Decide what is serializable — values and stable, resolvable references — and forbid smuggling live objects or ambient handles that will not survive the trip.
  • Pack the minimum context. Include the identity, config version, inputs, and secret references the job needs; exclude the ambient environment it must not inherit.
  • Gate rehydration. On pickup, the worker validates version and schema compatibility, checks authorization and identity, and reconstitutes references before running — rejecting or quarantining anything missing, incompatible, or expired.
  • Bound the lifetime. Attach time-to-live, retry, and dead-letter policy so a job that waits too long or fails repeatedly is disposed of rather than executed against a drifted world.

Tuning parameters

  • Value vs. reference in the payload — embedding values makes the envelope self-sufficient and reproducible but larger and staler; carrying references keeps it small and fresh but dependent on those references still resolving at pickup.
  • Strictness of the rehydration gate — how hard the worker checks versions, identity, and authorization before running; stricter is safer but rejects more borderline jobs.
  • Time-to-live and retry/backoff — how long a job may wait and how many times it retries before dead-lettering; long TTLs tolerate outages but risk acting on stale context.
  • Payload minimization — how aggressively to trim what travels; smaller envelopes are cheaper and leak less, but under-packing forces ambient fallback.
  • Idempotency key — whether the envelope carries a key so a redelivered job takes effect only once.

When it helps, and when it misleads

Its strength is being the archetype's answer for work that crosses a time or process gap — queues, schedulers, durable workflows — letting a job resume elsewhere, later, by another worker with the context it was defined under. The rehydration gate turns silent version drift into an explicit, catchable rejection.

The sharp failures are serialization loss (a needed binding did not survive, so the worker silently falls back to ambient state), version mismatch (the job rehydrates against a schema or rule that has moved), and rehydration under the wrong principal (it runs with the worker's identity instead of the delegator's). The classic misuse is stuffing the whole environment — or a raw secret — into the envelope because minimizing is inconvenient, producing bloated, leaky messages. Because durable delivery is usually at-least-once, a non-idempotent job can also take effect twice.[1] The discipline is to pack the minimum, reference secrets rather than embed them, and let the rehydration gate — not the serializer's defaults — decide what is safe to run.

How it implements the components

  • portability_and_serialization_contract — the envelope defines exactly what may be serialized and how it is reconstituted, the contract that makes the work portable.
  • rehydration_validation_gate — the receiving worker validates version, identity, and authorization and reconstitutes references before executing.
  • context_retention_and_disposal_rule — time-to-live, retry, and dead-letter policy govern how long the job may wait and when it is discarded rather than run stale.

It moves work; it does not decide the work's authority or vouch for its context. Scoped, revocable permission travels as a Revocable Authority Token; the version-and-provenance record it validates against is a Versioned Context Manifest; a tamper-evident seal over that record is a Signed Context Manifest; and confirming the rehydrated job behaves like the original is a Dual-Run Equivalence Test.

References

[1] Durable queues typically guarantee at-least-once delivery, so an envelope may be delivered and executed more than once — after a worker crash, say. Carrying an idempotency key, a token that lets the handler recognize and collapse duplicate deliveries, is the standard way to keep "run later, elsewhere" from becoming "run twice." ↩