docs: clarify job callback contract

README.md

@@ -107,9 +107,20 @@ Jobs can return the following values from `perform/2`:
 | `:ok` | Job completed successfully |
 | `{:ok, result}` | Job completed with result |
 | `{:error, reason}` | Job failed, will retry with backoff |
-| `{:snooze, ms}` | Reschedule job after delay |
+| `{:snooze, ms}` | Reschedule job after delay and count it in retry accounting |
 | `{:discard, reason}` | Discard job without retrying |
 
+## Job Metadata
+
+The second argument to `perform/2` is a metadata map for the current job:
+
+| Field | Description |
+| ----- | ----------- |
+| `:topic` | Topic string used to route the job |
+| `:queue_id` | Queue or tenant identifier used for fairness |
+| `:item_id` | Unique identifier for the queued item |
+| `:attempt` | Current 1-based attempt number |
+
 ## Interactive Tutorial
 
 [![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbedrock-kv%2Fjob_queue%2Frefs%2Fheads%2Fmain%2Flivebooks%2Fcoffee_shop.livemd)

lib/bedrock/job_queue/consumer/worker.ex

@@ -37,7 +37,7 @@ defmodule Bedrock.JobQueue.Consumer.Worker do
   - `{:ok, result}` - Job completed with result (logged but otherwise same as `:ok`)
   - `{:error, reason}` - Job failed, will be requeued with backoff
   - `{:discard, reason}` - Job failed permanently, removed without retry
-  - `{:snooze, delay_ms}` - Reschedule for later without counting as failure
+  - `{:snooze, delay_ms}` - Reschedule for later and count it in retry accounting
   - `{:error, :timeout}` - Job exceeded timeout, will be requeued
   - `{:discard, :no_handler}` - No worker configured for this topic
 

lib/bedrock/job_queue/job.ex

@@ -43,7 +43,7 @@ defmodule Bedrock.JobQueue.Job do
   - `{:ok, result}` - Job completed with a result (logged but otherwise ignored)
   - `{:error, reason}` - Job failed, will be retried if attempts remain
   - `{:discard, reason}` - Job failed permanently, won't be retried
-  - `{:snooze, delay_ms}` - Reschedule job for later without counting as a retry
+  - `{:snooze, delay_ms}` - Reschedule job for later and count it in retry accounting
 
   ## Meta