> ## Documentation Index
> Fetch the complete documentation index at: https://headgate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust tasks

> Derive typed JSON tasks and create durable envelopes.

```rust theme={"system"}
use headgate::Task;

#[derive(serde::Serialize, serde::Deserialize, Task)]
#[task(kind = "invoice.generate", version = 1)]
struct GenerateInvoice { invoice_id: String }

let task = GenerateInvoice { invoice_id: "inv-42".into() };
let payload = task.encode()?;
let envelope = headgate::Envelope {
    id: "invoice-job-42".into(),
    kind: GenerateInvoice::TYPE.into(),
    schema_version: GenerateInvoice::VERSION,
    fingerprint: headgate::fingerprint(GenerateInvoice::TYPE, &payload),
    payload,
    queue: "billing".into(),
    partition_key: "tenant-7".into(),
    ..Default::default()
};
```

<Note>
  Kind and schema version are durable public contracts. Keep the kind stable and set the
  envelope's `schema_version` explicitly. The derived `Task` rejects other versions by
  default. Custom upcasting currently needs a manual `impl Task` instead of `#[derive(Task)]`.
</Note>

See [Task versioning](/docs/guides/task-versioning) for a complete welcome-email v1 → v2 → v3
implementation, including the current-version decode arm and rolling-deployment guidance.