django-lambda-tasks 0.1.3__tar.gz → 0.1.5__tar.gz

django_lambda_tasks-0.1.5/.kiro/specs/retry-delay/.config.kiro

@@ -0,0 +1 @@
+{"specId": "d39d74d4-303d-471c-b297-79795f66ea87", "workflowType": "requirements-first", "specType": "feature"}

django_lambda_tasks-0.1.5/.kiro/specs/retry-delay/design.md

@@ -0,0 +1,315 @@
+# Design Document: retry-delay
+
+## Overview
+
+This feature adds a `retry_delay` parameter to the `@lambda_task` decorator, giving task authors explicit control over the SQS `DelaySeconds` used when a task is automatically re-enqueued after a retryable failure.
+
+As part of this change, the call-time `_delay` override kwarg accepted by `execute_on_commit()` is removed. Delay configuration is centralised on the decorator — there are no per-call overrides.
+
+The two delay resolution paths remain entirely separate after this change:
+
+- **Normal enqueue** (`execute_on_commit` called directly by application code): uses `self._delay` from the decorator.
+- **Retry enqueue** (triggered by a retryable exception in the executor): uses `min(wrapper.retry_delay + round(random.uniform(1, 5)), 900)` — jitter is always added, capped at 900.
+
+Both `delay` and `retry_delay` are validated at decoration time against the SQS maximum `DelaySeconds` of 900 seconds. `retry_delay` is additionally validated to require a non-empty `retry_on` tuple when non-zero.
+
+## Architecture
+
+No new modules are introduced. Changes are confined to three files:
+
+```
+lambda_tasks/
+  decorators.py   — add retry_delay param, validation, property; remove _delay pop in _build_task
+  models.py       — update retry path to use wrapper.retry_delay; remove _delay kwarg from retry enqueue
+.kiro/steering/
+  product.md      — update Enqueuing section and retry_on retry delay description
+```
+
+The flow after this change:
+
+```
+execute_on_commit(**kwargs)
+  → _build_task(kwargs)          # pops only _n_retries; uses self._delay directly
+  → SQSLambdaTask(delay=self._delay, ...)
+
+execute_immediately() retry path
+  → delay = wrapper.retry_delay if wrapper.retry_delay != 0 else round(random.uniform(1, 5))
+  → SQSLambdaTask(message=..., delay=delay, queue=wrapper.queue).execute_on_commit()
+```
+
+## Components and Interfaces
+
+### `LambdaTaskWrapper.__init__` (decorators.py)
+
+Add `retry_delay: int = 0` to the parameter list. Call two new validation methods before `functools.update_wrapper`. Store as `self._retry_delay`.
+
+```python
+def __init__(
+    self,
+    func: Callable[..., Any],
+    *,
+    delay: int = 0,
+    retry_delay: int = 0,
+    soft_timeout: int | None = None,
+    hard_timeout: int | None = None,
+    queue: str = "default",
+    ignore_errors: tuple[type[BaseException], ...] = (),
+    retry_on: tuple[type[BaseException], ...] = (),
+) -> None:
+    self._validate_func(func=func)
+    self._validate_timeouts(soft_timeout=soft_timeout, hard_timeout=hard_timeout)
+    self._validate_delay(delay=delay)
+    self._validate_retry_delay(retry_delay=retry_delay, retry_on=retry_on)
+    self._validate_ignore_errors(ignore_errors=ignore_errors)
+    self._validate_retry_on(retry_on=retry_on)
+    self._validate_no_overlap(retry_on=retry_on, ignore_errors=ignore_errors)
+    ...
+    self._retry_delay = retry_delay
+```
+
+### `LambdaTaskWrapper.retry_delay` property (decorators.py)
+
+Expose `_retry_delay` as a read-only property, mirroring the existing `retry_on` and `ignore_errors` properties:
+
+```python
+@property
+def retry_delay(self) -> int:
+    """Delay in seconds used when enqueuing a retry. 0 means use jitter."""
+    return self._retry_delay
+```
+
+### `LambdaTaskWrapper._validate_delay` (decorators.py)
+
+New static method. Validates `delay` is in `[0, 900]`:
+
+```python
+@staticmethod
+def _validate_delay(*, delay: int) -> None:
+    if delay < 0 or delay > 900:
+        raise ValueError(
+            f"delay ({delay}) must be in the range [0, 900] (SQS maximum DelaySeconds)."
+        )
+```
+
+### `LambdaTaskWrapper._validate_retry_delay` (decorators.py)
+
+New static method. Validates `retry_delay` is in `[0, 900]` and, if non-zero, that `retry_on` is non-empty:
+
+```python
+@staticmethod
+def _validate_retry_delay(
+    *, retry_delay: int, retry_on: tuple[type[BaseException], ...]
+) -> None:
+    if retry_delay < 0 or retry_delay > 900:
+        raise ValueError(
+            f"retry_delay ({retry_delay}) must be in the range [0, 900] (SQS maximum DelaySeconds)."
+        )
+    if retry_delay != 0 and not retry_on:
+        raise TypeError(
+            "retry_delay is only meaningful when retry_on is non-empty. "
+            "Either set retry_on or remove retry_delay."
+        )
+```
+
+### `LambdaTaskWrapper._build_task` (decorators.py)
+
+Remove the `_delay` pop. Use `self._delay` directly. Only `_n_retries` is still popped from kwargs:
+
+```python
+def _build_task(self, *, kwargs: dict[str, Any]) -> SQSLambdaTask:
+    n_retries = kwargs.pop("_n_retries", 0)
+
+    self._kwargs_model.model_validate(kwargs)
+
+    message = SQSLambdaTaskMessage(
+        task_name=f"{self._func.__module__}.{self._func.__qualname__}",
+        kwargs=dict(kwargs),
+        n_retries=n_retries,
+    )
+
+    return SQSLambdaTask(
+        message=message,
+        delay=self._delay,
+        queue=self._queue,
+    )
+```
+
+The docstring for `_build_task`, `serialize`, and `execute_on_commit` must also drop all references to `_delay`.
+
+### `lambda_task` decorator factory (decorators.py)
+
+Add `retry_delay: int = 0` to both `@overload` signatures and the implementation. Pass it through to `LambdaTaskWrapper`:
+
+```python
+def lambda_task(
+    func: Callable[..., Any] | None = None,
+    *,
+    delay: int = 0,
+    retry_delay: int = 0,
+    soft_timeout: int | None = None,
+    hard_timeout: int | None = None,
+    queue: str = "default",
+    ignore_errors: tuple[type[BaseException], ...] = (),
+    retry_on: tuple[type[BaseException], ...] = (),
+) -> LambdaTaskWrapper | Callable[[Callable[..., Any]], LambdaTaskWrapper]:
+    def _decorate(f: Callable[..., Any]) -> LambdaTaskWrapper:
+        return LambdaTaskWrapper(
+            f,
+            delay=delay,
+            retry_delay=retry_delay,
+            ...
+        )
+    ...
+```
+
+### `SQSLambdaTaskMessage.execute_immediately` retry path (models.py)
+
+Replace the `wrapper._delay` reference with `wrapper.retry_delay`. Remove `_delay=delay` from the `execute_on_commit` call — `_build_task` no longer accepts it:
+
+```python
+# Before:
+delay = wrapper._delay if wrapper._delay != 0 else round(random.uniform(1, 5))
+wrapper.execute_on_commit(**self.kwargs, _delay=delay, _n_retries=self.n_retries + 1)
+
+# After:
+delay = wrapper.retry_delay if wrapper.retry_delay != 0 else round(random.uniform(1, 5))
+wrapper.execute_on_commit(**self.kwargs, _n_retries=self.n_retries + 1)
+```
+
+The `delay` local variable is still computed and used — it must be passed to `_build_task` via the retry enqueue. Since `_build_task` now uses `self._delay` directly for normal enqueues, the retry path needs a different mechanism to inject the computed delay.
+
+**Revised approach:** The retry enqueue cannot use `execute_on_commit` directly if `_delay` is removed, because `execute_on_commit` always uses `self._delay`. Instead, the retry path in `execute_immediately` should build the `SQSLambdaTask` directly and call `execute_on_commit` on it:
+
+```python
+delay = wrapper.retry_delay if wrapper.retry_delay != 0 else round(random.uniform(1, 5))
+retry_task = SQSLambdaTask(
+    message=SQSLambdaTaskMessage(
+        task_name=self.task_name,
+        kwargs=self.kwargs,
+        n_retries=self.n_retries + 1,
+    ),
+    delay=delay,
+    queue=wrapper._queue,
+)
+retry_task.execute_on_commit()
+```
+
+This avoids any need for a `_delay` override kwarg and keeps `_build_task` clean. The `wrapper._queue` access uses the private attribute — this is acceptable since `execute_immediately` is part of the same library and `_queue` has no public property. Alternatively, expose a `queue` property on `LambdaTaskWrapper` (preferred for clarity):
+
+```python
+@property
+def queue(self) -> str:
+    """The SQS queue name this task is routed to."""
+    return self._queue
+```
+
+Then the retry path becomes:
+
+```python
+delay = wrapper.retry_delay if wrapper.retry_delay != 0 else round(random.uniform(1, 5))
+retry_task = SQSLambdaTask(
+    message=SQSLambdaTaskMessage(
+        task_name=self.task_name,
+        kwargs=self.kwargs,
+        n_retries=self.n_retries + 1,
+    ),
+    delay=delay,
+    queue=wrapper.queue,
+)
+retry_task.execute_on_commit()
+```
+
+## Data Models
+
+No changes to `SQSLambdaTaskMessage`, `SQSLambdaTask`, or `TaskRecord` schemas. `retry_delay` is a decorator-level configuration value stored on `LambdaTaskWrapper` — it is never serialised into the SQS message.
+
+`LambdaTaskWrapper` gains one new stored attribute:
+
+| Attribute | Type | Description |
+|---|---|---|
+| `_retry_delay` | `int` | Seconds to delay a retry enqueue. 0 = use jitter. |
+
+Exposed via the `retry_delay` property.
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: retry_delay storage round-trip
+
+*For any* integer `retry_delay` in `[0, 900]` (with `retry_on` non-empty when `retry_delay > 0`), constructing a `LambdaTaskWrapper` and reading `wrapper.retry_delay` SHALL return the same value that was passed in.
+
+**Validates: Requirements 1.2**
+
+### Property 2: retry_delay requires retry_on
+
+*For any* integer `retry_delay` in `[1, 900]`, constructing a `LambdaTaskWrapper` with an empty `retry_on` tuple SHALL raise `TypeError`.
+
+**Validates: Requirements 1.4**
+
+### Property 3: Out-of-range delay and retry_delay raise ValueError
+
+*For any* integer `delay` outside `[0, 900]`, constructing a `LambdaTaskWrapper` SHALL raise `ValueError`. Likewise, *for any* integer `retry_delay` outside `[0, 900]`, constructing a `LambdaTaskWrapper` SHALL raise `ValueError`.
+
+**Validates: Requirements 2.1, 2.2**
+
+### Property 4: Non-zero retry_delay is used in the retry enqueue
+
+*For any* `retry_delay` in `[1, 900]` and any retryable exception, the `SQSLambdaTask` enqueued by the retry path SHALL have `delay == retry_delay`.
+
+**Validates: Requirements 3.1**
+
+### Property 5: Zero retry_delay produces jitter in [1, 5]
+
+*For any* execution where `retry_delay` is `0` and a retryable exception is raised, the `delay` on the enqueued retry `SQSLambdaTask` SHALL be an integer in the inclusive range `[1, 5]`.
+
+**Validates: Requirements 3.2, 3.3**
+
+### Property 6: Normal enqueue uses decorator delay
+
+*For any* `delay` in `[0, 900]`, calling `execute_on_commit` directly (not via the retry path) SHALL produce a `SQSLambdaTask` with `delay` equal to the decorator-configured value.
+
+**Validates: Requirements 4.3, 4.4**
+
+## Error Handling
+
+| Condition | Error | Raised at |
+|---|---|---|
+| `delay < 0` or `delay > 900` | `ValueError` | Decoration time |
+| `retry_delay < 0` or `retry_delay > 900` | `ValueError` | Decoration time |
+| `retry_delay != 0` and `retry_on == ()` | `TypeError` | Decoration time |
+| `_delay` passed to `execute_on_commit()` | `TypeError` (from pydantic `extra="forbid"` on the kwargs model, or from `_build_task` rejecting it) | Call time |
+
+The `_delay` rejection at call time is a natural consequence of removing the `kwargs.pop("_delay", ...)` line from `_build_task`. If `_delay` is passed, it will reach `self._kwargs_model.model_validate(kwargs)` and be rejected by the `extra="forbid"` Pydantic config with a `ValidationError`. This is acceptable — the public contract says `_delay` is no longer supported, and the error message from Pydantic is clear enough. No special handling is needed.
+
+## Testing Strategy
+
+Tests use `pytest` and `hypothesis` (already present in the project).
+
+**Unit tests** (`tests/test_decorators.py`):
+- `retry_delay` defaults to `0`
+- `retry_delay` is stored and returned via the property
+- `retry_delay=0` with empty `retry_on` is accepted (default case)
+- `retry_delay > 0` with non-empty `retry_on` is accepted
+- `retry_delay > 0` with empty `retry_on` raises `TypeError`
+- `delay < 0` raises `ValueError`; `delay > 900` raises `ValueError`
+- `retry_delay < 0` raises `ValueError`; `retry_delay > 900` raises `ValueError`
+- `delay=0` and `delay=900` are accepted (boundary values)
+- `_delay` passed to `execute_on_commit` raises (via Pydantic `ValidationError`)
+- `lambda_task` decorator factory passes `retry_delay` through correctly
+
+**Unit tests** (`tests/test_models.py`):
+- Retry path with non-zero `retry_delay` enqueues with that exact delay
+- Retry path with `retry_delay=0` enqueues with a delay in `[1, 5]`
+- Normal `execute_on_commit` uses decorator `delay`, not `retry_delay`
+
+**Property-based tests** (using `hypothesis`, in `tests/test_decorators.py` and `tests/test_models.py`):
+
+Each property test runs a minimum of 100 iterations.
+
+- **Feature: retry-delay, Property 1**: `@given(st.integers(min_value=0, max_value=900))` — verify `wrapper.retry_delay == input`
+- **Feature: retry-delay, Property 2**: `@given(st.integers(min_value=1, max_value=900))` — verify `TypeError` raised with empty `retry_on`
+- **Feature: retry-delay, Property 3**: `@given(st.integers().filter(lambda x: x < 0 or x > 900))` — verify `ValueError` for both `delay` and `retry_delay`
+- **Feature: retry-delay, Property 4**: `@given(st.integers(min_value=1, max_value=900))` — mock retry enqueue, verify `task.delay == retry_delay`
+- **Feature: retry-delay, Property 5**: `@given(st.integers(min_value=0, max_value=0))` with repeated sampling — verify jitter delay in `[1, 5]`
+- **Feature: retry-delay, Property 6**: `@given(st.integers(min_value=0, max_value=900))` — mock enqueue, verify `task.delay == decorator delay`

django_lambda_tasks-0.1.5/.kiro/specs/retry-delay/requirements.md

@@ -0,0 +1,72 @@
+# Requirements Document
+
+## Introduction
+
+Add a `retry_delay` parameter to the `@lambda_task` decorator that gives callers explicit control over the delay (in seconds) used when a task is automatically re-enqueued after a retryable failure.
+
+As part of this feature, the call-time `_delay` override kwarg accepted by `execute_on_commit()` is being removed. The `product.md` steering doc currently documents `execute_on_commit()` as accepting `_delay` as a per-call override — this behaviour is being removed.
+
+The two delay resolution paths are entirely separate:
+
+- **Normal enqueue** (`execute_on_commit` called directly): decorator `delay` only (no call-time override)
+- **Retry enqueue** (triggered by a retryable exception): `min(retry_delay + round(random.uniform(1, 5)), 900)` — jitter is always added, capped at 900
+
+`retry_delay` is only meaningful when `retry_on` is also configured. Setting `retry_delay` without `retry_on` raises `TypeError` at decoration time.
+
+Both `delay` and `retry_delay` are validated at decoration time against the SQS maximum `DelaySeconds` of 900 seconds.
+
+## Glossary
+
+- **Decorator**: The `@lambda_task` decorator factory defined in `decorators.py`.
+- **LambdaTaskWrapper**: The object produced by applying `@lambda_task` to a function; stores all decorator-level configuration.
+- **Executor**: `SQSLambdaTaskMessage.execute_immediately()` in `models.py`; runs the task and handles retries.
+- **retry_delay**: The new decorator parameter — a non-negative integer (seconds) used as the base SQS `DelaySeconds` when enqueuing a retry. Jitter is always added on top. Not used for normal enqueues.
+- **delay**: The existing decorator parameter — a non-negative integer (seconds) used as the SQS `DelaySeconds` for normal (non-retry) enqueues only.
+- **Jitter**: Random delay of `round(random.uniform(1, 5))` seconds, always added to `retry_delay` when enqueuing a retry. The total is capped at 900.
+- **retry_on**: The existing decorator parameter — a tuple of exception types that trigger automatic retry.
+- **SQS_MAX_DELAY**: The SQS maximum allowed `DelaySeconds` value: 900 seconds.
+
+## Requirements
+
+### Requirement 1: retry_delay Decorator Parameter
+
+**User Story:** As a task author, I want to set a dedicated retry delay on my task decorator, so that retries use a predictable delay independent of the normal enqueue delay.
+
+#### Acceptance Criteria
+
+1. THE Decorator SHALL accept a `retry_delay` keyword argument of type `int` with a default value of `0`.
+2. THE LambdaTaskWrapper SHALL store the `retry_delay` value and expose it via a `retry_delay` property.
+3. WHEN `retry_delay` is set to a non-zero value and `retry_on` is a non-empty tuple, THE Decorator SHALL construct the LambdaTaskWrapper without raising an exception.
+4. IF `retry_delay` is non-zero and `retry_on` is an empty tuple or not provided, THEN THE Decorator SHALL raise a `TypeError` at decoration time.
+
+### Requirement 2: Validation of delay and retry_delay at Decoration Time
+
+**User Story:** As a task author, I want invalid delay values to be caught immediately when I define my task, so that misconfiguration is surfaced before any task is ever enqueued.
+
+#### Acceptance Criteria
+
+1. IF `delay` is less than `0` or greater than `900`, THEN THE Decorator SHALL raise a `ValueError` at decoration time.
+2. IF `retry_delay` is less than `0` or greater than `900`, THEN THE Decorator SHALL raise a `ValueError` at decoration time.
+3. WHEN `delay` is an integer in the inclusive range `[0, 900]`, THE Decorator SHALL accept it without raising an exception.
+4. WHEN `retry_delay` is an integer in the inclusive range `[0, 900]`, THE Decorator SHALL accept it without raising an exception.
+
+### Requirement 3: Retry Delay Resolution
+
+**User Story:** As a task author, I want retries to use `retry_delay` when set, and fall back to jitter otherwise, so that retry timing is predictable when configured and safe when not.
+
+#### Acceptance Criteria
+
+1. WHEN a retryable exception is raised and `retry_delay` is non-zero, THE Executor SHALL enqueue the retry with `DelaySeconds` set to `retry_delay`.
+2. WHEN a retryable exception is raised and `retry_delay` is zero, THE Executor SHALL enqueue the retry with `DelaySeconds` set to `round(random.uniform(1, 5))`.
+3. WHEN a retryable exception is raised and `retry_delay` is zero, THE Executor SHALL produce a `DelaySeconds` value in the inclusive integer range `[1, 5]`.
+
+### Requirement 4: Remove Call-Time _delay Override
+
+**User Story:** As a library maintainer, I want to remove the `_delay` per-call override from `execute_on_commit()`, so that delay configuration is centralised on the decorator and the public API is simpler.
+
+#### Acceptance Criteria
+
+1. THE LambdaTaskWrapper SHALL NOT accept `_delay` as a kwarg in `execute_on_commit()`.
+2. IF `_delay` is passed to `execute_on_commit()`, THEN THE LambdaTaskWrapper SHALL raise a `TypeError`.
+3. WHEN `execute_on_commit` is called directly (not as a retry), THE LambdaTaskWrapper SHALL resolve `DelaySeconds` using only the decorator `delay` value.
+4. THE LambdaTaskWrapper SHALL NOT use `retry_delay` when building a task for a non-retry enqueue.

django_lambda_tasks-0.1.5/.kiro/specs/retry-delay/tasks.md

@@ -0,0 +1,182 @@
+# Implementation Plan: retry-delay
+
+## Overview
+
+Add `retry_delay` to `@lambda_task`, remove the `_delay` call-time override from `execute_on_commit`, and update the retry path in `execute_immediately` to use `wrapper.retry_delay` directly via a `SQSLambdaTask` built in-place. Follow red/green TDD: tests are written before each implementation step.
+
+## Tasks
+
+- [x] 1. Add `_validate_delay` to `LambdaTaskWrapper`
+  - [x] 1.1 Write failing tests for `_validate_delay`
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - `delay < 0` raises `ValueError`
+      - `delay > 900` raises `ValueError`
+      - `delay=0` and `delay=900` are accepted (boundary values)
+    - Tests must fail before implementation exists
+    - _Requirements: 2.1, 2.3_
+  - [x] 1.2 Implement `_validate_delay` static method on `LambdaTaskWrapper`
+    - Add `@staticmethod _validate_delay(*, delay: int) -> None` to `LambdaTaskWrapper` in `decorators.py`
+    - Raises `ValueError` if `delay < 0` or `delay > 900`
+    - Call it from `__init__` (after `_validate_timeouts`)
+    - _Requirements: 2.1, 2.3_
+
+- [x] 2. Add `retry_delay` parameter and `_validate_retry_delay` to `LambdaTaskWrapper`
+  - [x] 2.1 Write failing tests for `retry_delay` init and `_validate_retry_delay`
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - `retry_delay` defaults to `0`
+      - `retry_delay=0` with empty `retry_on` is accepted
+      - `retry_delay > 0` with non-empty `retry_on` is accepted
+      - `retry_delay > 0` with empty `retry_on` raises `TypeError`
+      - `retry_delay < 0` raises `ValueError`
+      - `retry_delay > 900` raises `ValueError`
+    - Tests must fail before implementation exists
+    - _Requirements: 1.1, 1.3, 1.4, 2.2, 2.4_
+  - [x] 2.2 Implement `retry_delay` parameter and `_validate_retry_delay`
+    - Add `retry_delay: int = 0` to `LambdaTaskWrapper.__init__` signature
+    - Add `@staticmethod _validate_retry_delay(*, retry_delay: int, retry_on: tuple[type[BaseException], ...]) -> None`
+    - Raises `ValueError` if `retry_delay < 0` or `retry_delay > 900`
+    - Raises `TypeError` if `retry_delay != 0` and `retry_on` is empty
+    - Call it from `__init__` (after `_validate_delay`)
+    - Store as `self._retry_delay = retry_delay`
+    - _Requirements: 1.1, 1.3, 1.4, 2.2, 2.4_
+
+- [x] 3. Add `retry_delay` property to `LambdaTaskWrapper`
+  - [x] 3.1 Write failing tests for `retry_delay` property
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - `wrapper.retry_delay` returns the value passed at construction
+      - Default is `0`
+    - Tests must fail before implementation exists
+    - _Requirements: 1.2_
+  - [x] 3.2 Implement `retry_delay` property
+    - Add `@property retry_delay(self) -> int` to `LambdaTaskWrapper`, returning `self._retry_delay`
+    - Mirror the existing `retry_on` and `ignore_errors` property pattern
+    - _Requirements: 1.2_
+
+- [x] 4. Add `queue` property to `LambdaTaskWrapper`
+  - [x] 4.1 Write failing tests for `queue` property
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - `wrapper.queue` returns the queue name passed at construction
+      - Default is `"default"`
+    - Tests must fail before implementation exists
+  - [x] 4.2 Implement `queue` property
+    - Add `@property queue(self) -> str` to `LambdaTaskWrapper`, returning `self._queue`
+    - _Requirements: 3.1 (needed by retry path in models.py)_
+
+- [x] 5. Update `_build_task` to remove `_delay` pop and use `self._delay` directly
+  - [x] 5.1 Write failing tests for updated `_build_task` behaviour
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - Passing `_delay` as a kwarg to `execute_on_commit` raises (Pydantic `ValidationError` from `extra="forbid"`)
+      - Normal `execute_on_commit` without `_delay` still works and uses the decorator `delay`
+    - Tests must fail before implementation exists
+    - _Requirements: 4.1, 4.2, 4.3_
+  - [x] 5.2 Remove `_delay` pop from `_build_task`; use `self._delay` directly
+    - In `decorators.py`, remove `delay = kwargs.pop("_delay", self._delay)` from `_build_task`
+    - Replace with `delay = self._delay` (no pop)
+    - Only `_n_retries` is still popped from kwargs
+    - Update `_build_task` docstring to remove all `_delay` references
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+
+- [x] 6. Update `execute_on_commit` and `serialize` docstrings
+  - Remove all references to `_delay` from the docstrings of `execute_on_commit` and `serialize` in `decorators.py`
+  - No behaviour change — docstring-only update
+  - _Requirements: 4.1_
+
+- [x] 7. Add `retry_delay` to the `lambda_task` decorator factory
+  - [x] 7.1 Write failing tests for `lambda_task` forwarding `retry_delay`
+    - In `tests/test_decorators.py`, add unit tests asserting:
+      - `@lambda_task(retry_delay=30, retry_on=(ValueError,))` produces `wrapper.retry_delay == 30`
+      - `@lambda_task` without `retry_delay` produces `wrapper.retry_delay == 0`
+    - Tests must fail before implementation exists
+    - _Requirements: 1.1, 1.2_
+  - [x] 7.2 Add `retry_delay` to both `@overload` signatures and the `lambda_task` implementation
+    - Add `retry_delay: int = 0` to both `@overload` stubs and the concrete `lambda_task` function in `decorators.py`
+    - Pass `retry_delay=retry_delay` through to `LambdaTaskWrapper(...)` inside `_decorate`
+    - _Requirements: 1.1_
+
+- [x] 8. Checkpoint — ensure all decorator tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 9. Update `execute_immediately` retry path in `models.py`
+  - [x] 9.1 Write failing tests for the updated retry path
+    - In `tests/test_models.py`, add unit tests asserting:
+      - Retry path with non-zero `retry_delay` enqueues a `SQSLambdaTask` with `delay == retry_delay`
+      - Retry path with `retry_delay=0` enqueues a `SQSLambdaTask` with `delay` in `[1, 5]`
+      - Normal `execute_on_commit` (non-retry) uses the decorator `delay`, not `retry_delay`
+      - Passing `_delay` to `execute_on_commit` raises `ValidationError`
+    - Tests must fail before implementation exists
+    - _Requirements: 3.1, 3.2, 3.3, 4.1, 4.2_
+  - [x] 9.2 Update the retry path in `SQSLambdaTaskMessage.execute_immediately`
+    - Replace `wrapper._delay` with `wrapper.retry_delay` for the delay resolution
+    - Replace the `wrapper.execute_on_commit(**self.kwargs, _delay=delay, _n_retries=...)` call with a direct `SQSLambdaTask` construction and `execute_on_commit()`:
+      ```python
+      delay = wrapper.retry_delay if wrapper.retry_delay != 0 else round(random.uniform(1, 5))
+      retry_task = SQSLambdaTask(
+          message=SQSLambdaTaskMessage(
+              task_name=self.task_name,
+              kwargs=self.kwargs,
+              n_retries=self.n_retries + 1,
+          ),
+          delay=delay,
+          queue=wrapper.queue,
+      )
+      retry_task.execute_on_commit()
+      ```
+    - _Requirements: 3.1, 3.2, 3.3_
+
+- [x] 10. Update `product.md` steering doc
+  - In `.kiro/steering/product.md`:
+    - Update the `## Enqueuing` section: remove `_delay` from the list of per-call overrides; state that `execute_on_commit()` uses only the decorator `delay` value
+    - Update the `## retry_on` section: replace the "Retry delay" paragraph to describe `retry_delay` (non-zero → use `retry_delay`; zero → jitter `round(random.uniform(1, 5))`)
+    - Add `retry_delay` to the `## Task Definition` example snippet
+  - _Requirements: 4.1_
+
+- [x] 11. Checkpoint — ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 12. Property-based tests (hypothesis) for the 6 correctness properties
+  - [x] 12.1 Property 1: `retry_delay` storage round-trip
+    - In `tests/test_decorators.py`, add `@given(st.integers(min_value=0, max_value=900))`
+    - For `retry_delay=0`: construct with empty `retry_on`; for `retry_delay > 0`: construct with `retry_on=(ValueError,)`
+    - Assert `wrapper.retry_delay == input`
+    - **Property 1: retry_delay storage round-trip**
+    - **Validates: Requirements 1.2**
+  - [x] 12.2 Property 2: `retry_delay` requires `retry_on`
+    - In `tests/test_decorators.py`, add `@given(st.integers(min_value=1, max_value=900))`
+    - Construct `LambdaTaskWrapper` with `retry_delay=value` and empty `retry_on`
+    - Assert `TypeError` is raised
+    - **Property 2: retry_delay requires retry_on**
+    - **Validates: Requirements 1.4**
+  - [x] 12.3 Property 3: out-of-range `delay` and `retry_delay` raise `ValueError`
+    - In `tests/test_decorators.py`, add `@given(st.integers().filter(lambda x: x < 0 or x > 900))`
+    - Test both `delay=value` and `retry_delay=value` (with `retry_on=(ValueError,)` for the latter)
+    - Assert `ValueError` is raised in both cases
+    - **Property 3: out-of-range delay and retry_delay raise ValueError**
+    - **Validates: Requirements 2.1, 2.2**
+  - [x] 12.4 Property 4: non-zero `retry_delay` is used in the retry enqueue
+    - In `tests/test_models.py`, add `@given(st.integers(min_value=1, max_value=900))`
+    - Mock `SQSLambdaTask.execute_on_commit` or capture the constructed task; trigger a retryable exception
+    - Assert the enqueued `SQSLambdaTask.delay == retry_delay`
+    - **Property 4: non-zero retry_delay is used in the retry enqueue**
+    - **Validates: Requirements 3.1**
+  - [x] 12.5 Property 5: zero `retry_delay` produces jitter in `[1, 5]`
+    - In `tests/test_models.py`, use repeated sampling (e.g. 100 iterations) with `retry_delay=0`
+    - Assert every enqueued delay is an integer in `[1, 5]`
+    - **Property 5: zero retry_delay produces jitter in [1, 5]**
+    - **Validates: Requirements 3.2, 3.3**
+  - [x] 12.6 Property 6: normal enqueue uses decorator `delay`
+    - In `tests/test_decorators.py` or `tests/test_models.py`, add `@given(st.integers(min_value=0, max_value=900))`
+    - Call `execute_on_commit` directly (not via retry path); capture the `SQSLambdaTask`
+    - Assert `task.delay == decorator delay`
+    - **Property 6: normal enqueue uses decorator delay**
+    - **Validates: Requirements 4.3, 4.4**
+
+- [x] 13. Final checkpoint — ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- TDD order is strict: each `x.1` test task must be completed before its `x.2` implementation task
+- Existing tests for `_delay` call-time override (e.g. `test_property_on_commit_delay_embedded_in_sqs_message` and `test_property_10_non_zero_delay_used_as_retry_delay`) will need to be updated or removed as part of tasks 5 and 9 — they test behaviour that is being removed
+- `retry_delay` is never serialised into the SQS message; it lives only on `LambdaTaskWrapper`
+- Property tests use `min_examples=100` per the design doc

django_lambda_tasks-0.1.5/.kiro/specs/singleton-task/.config.kiro

@@ -0,0 +1 @@
+{"specId": "d39d74d4-303d-471c-b297-79795f66ea87", "workflowType": "requirements-first", "specType": "feature"}