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

# Core Concepts

> The vocabulary behind Durable Jobs: jobs, steps, runs, queues, state, events, and idempotency.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Learn the small set of concepts needed to build reliable backend flows.

## Prerequisites

* Read the Durable Jobs overview

## Workflow

<Steps>
  <Step>
    Start with a job definition.
  </Step>

  <Step>
    Think of every execution as a run.
  </Step>

  <Step>
    Use steps for work that should not repeat after it succeeds.
  </Step>

  <Step>
    Use queues to control background execution.
  </Step>

  <Step>
    Use state, events, and idempotency to make external systems safe.
  </Step>
</Steps>

## Jobs and runs

A job is the named unit of work. A run is one execution of that job with a payload, status, attempts, timeline, and result.

<CodeGroup>
  ```ts Define and start a job theme={null}
  stackshift.job('resizeAvatar', async ({ payload }) => {
    return resizeImage(payload)
  })

  await stackshift.start('resizeAvatar', { imageId: 'img_123' }, {
    queueName: 'media',
    idempotencyKey: 'resize:img_123',
  })
  ```

  ```go Go theme={null}
  client.Job("resizeAvatar", func(ctx context.Context, job stackshift.JobContext) (any, error) {
    return resizeImage(job.Payload)
  })

  _, err := client.Start(ctx, "resizeAvatar", map[string]any{
    "imageId": "img_123",
  }, &stackshift.StartOptions{
    QueueName: "media",
    IdempotencyKey: "resize:img_123",
  })
  ```
</CodeGroup>

## Steps

A step is a named unit inside a job. If a retry happens after a step completes, StackShift reuses the step result instead of running it again.

```ts Remember completed work theme={null}
await step.run('charge-card', async () => {
  return stripe.paymentIntents.capture(paymentIntentId)
})

await step.run('provision-plan', async () => {
  return provisionWorkspace(userId)
})
```

## Queues, state, events, and idempotency

* Queues decide where and when background work runs.
* State stores durable values such as progress, counters, dedupe markers, and locks.
* Events resume paused workflows when an external signal arrives.
* Idempotency keys ensure duplicate starts reuse the same logical run instead of doing the work twice.

## Expected result

<Check>
  The Durable Jobs API reads as one system instead of separate queue, workflow, and state products.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Using Queues" href="/durable-jobs/using-queues">
    Use queues for background execution, retry policy, delayed jobs, and concurrency control.
  </Card>

  <Card title="State Store" href="/durable-jobs/state-store">
    Use durable state for progress, deduplication, counters, TTL-backed markers, and locks.
  </Card>

  <Card title="Event Waiting + Correlation" href="/durable-jobs/event-waiting-and-correlation">
    Pause a workflow until the right external event arrives, then resume the correct run.
  </Card>

  <Card title="Idempotency" href="/durable-jobs/idempotency">
    Use idempotency keys so duplicate requests do not create duplicate work.
  </Card>
</CardGroup>