fix: include positional args in the deduplication fingerprint (#81)

docs/index.md

@@ -55,7 +55,7 @@ except DuplicateTaskError:
 - **Configurable TTL** — set a global default or override per task with the `deduplication_ttl` label.
 - **Lock heartbeat** — a background task re-extends the lock TTL while the task runs, so long-running tasks keep their lock instead of expiring mid-execution and admitting a duplicate.
 - **Explicit lock key** — pin any task to a fixed Redis key with `deduplication_key`, bypassing fingerprint computation entirely.
-- **Partial fingerprint** — deduplicate on a subset of kwargs with `deduplication_key_fields`, ignoring irrelevant arguments.
+- **Partial fingerprint** — deduplicate on a subset of kwargs with `deduplication_key_fields`, ignoring irrelevant arguments (positional arguments are excluded).
 - **Per-task opt-out** — disable deduplication for individual tasks with the `deduplication` label.
 - **Startup resilience** — automatic reconnection with exponential backoff if Redis is unavailable at broker startup.
 

docs/usage.md

@@ -147,11 +147,19 @@ await my_task.kicker().with_labels(deduplication_ttl=60).kiq(user_id=42)
 | `deduplication` | `bool` | Set `False` to opt out of deduplication entirely for this task. |
 | `deduplication_ttl` | `int` | Lock TTL in seconds. Overrides the middleware `default_ttl`. |
 | `deduplication_key` | `str` | Explicit lock key. Skips fingerprint computation entirely. |
-| `deduplication_key_fields` | `list[str]` | Subset of kwargs to include in the fingerprint. Ignored if `deduplication_key` is set. |
+| `deduplication_key_fields` | `list[str]` | Subset of kwargs to include in the fingerprint. Positional arguments are excluded. Ignored if `deduplication_key` is set. |
 
 ## Fingerprint and key customisation
 
-By default the lock key is a SHA-256 fingerprint of the task name and all kwargs.
+By default the lock key is a SHA-256 fingerprint of the task name, its positional
+arguments and all kwargs.
+
+!!! warning "Positional and keyword calls fingerprint differently"
+
+    taskiq serialises arguments as they were passed, without binding them to the
+    task signature. `my_task.kiq(42)` and `my_task.kiq(user_id=42)` are therefore
+    *not* recognised as duplicates of each other. Call a deduplicated task
+    consistently, preferably always with keyword arguments.
 
 ### Explicit key
 
@@ -182,6 +190,10 @@ If a listed field is absent from a task's kwargs, it is dropped from the
 fingerprint and a warning is logged, since this can make genuinely different
 calls collide on the same lock.
 
+Positional arguments are excluded from the fingerprint entirely when this label is
+set: you asked to deduplicate on named fields, so pass them as keyword arguments.
+A warning is logged if the task is called with positional arguments anyway.
+
 ## Opting out per task
 
 ```python