nexus-queue 0.1.1__tar.gz

nexus_queue-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env

nexus_queue-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

nexus_queue-0.1.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.1](https://github.com/Zetesis-Labs/PayloadAgents/compare/nexus-queue-v0.1.0...nexus-queue-v0.1.1) (2026-06-17)
+
+
+### Features
+
+* introduce the Nexus-Queue standard (runtime + TS client) ([fa0672c](https://github.com/Zetesis-Labs/PayloadAgents/commit/fa0672c17f87ca76c2eaf7dd3295417c560b6d40))
+* introduce the Nexus-Queue standard (runtime + TS client) ([73fce93](https://github.com/Zetesis-Labs/PayloadAgents/commit/73fce93fdc208efed95c573a1c89f69f1fc79d51))
+* **nexus-queue:** configure an OTLP tracing exporter when an endpoint is set ([a9167fa](https://github.com/Zetesis-Labs/PayloadAgents/commit/a9167fa33c8ce629d51176a48c38bc73ef700545))
+* **nexus-queue:** configure OTLP tracing exporter when endpoint set ([49e0ed8](https://github.com/Zetesis-Labs/PayloadAgents/commit/49e0ed8974ee217c23ebfca2d97e8883d8f34ad0))
+* **nexus-queue:** harden the worker runtime (idempotency, backoff, metrics) ([9e7804a](https://github.com/Zetesis-Labs/PayloadAgents/commit/9e7804abdb5f12414bcf91ea10fbca0d874b4f97))
+
+
+### Bug Fixes
+
+* **security:** timing-safe internal-secret compare + LlamaParse upload limits ([77ac5c6](https://github.com/Zetesis-Labs/PayloadAgents/commit/77ac5c6954abb196b25f3cb3ef0fe120fa32ca28))

nexus_queue-0.1.1/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: nexus-queue
+Version: 0.1.1
+Summary: Nexus-Queue — portable taskiq + Redis Streams worker runtime: namespaced streams, versioned envelope, ports-and-adapters, retry/DLQ/idempotency/tracing/metrics middleware.
+Project-URL: Homepage, https://github.com/Zetesis-Labs/PayloadAgents
+Project-URL: Repository, https://github.com/Zetesis-Labs/PayloadAgents
+Project-URL: Issues, https://github.com/Zetesis-Labs/PayloadAgents/issues
+Author: Zetesis Labs
+License: MIT
+Keywords: dlq,ports-and-adapters,queue,redis,taskiq,worker
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: opentelemetry-api>=1.35
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35
+Requires-Dist: opentelemetry-sdk>=1.35
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: pydantic>=2.9
+Requires-Dist: redis>=5.0
+Requires-Dist: structlog>=24.1
+Requires-Dist: taskiq-redis>=1.1.1
+Requires-Dist: taskiq>=0.11.18
+Requires-Dist: uvicorn[standard]>=0.34
+Description-Content-Type: text/markdown
+
+# nexus-queue
+
+Portable worker runtime for the **Nexus-Queue** standard: taskiq + Redis Streams,
+domain-agnostic, ports-and-adapters. One project builds queues the same way as
+the next, and a worker's handlers move between projects unchanged.
+
+What this package owns (the parts that are the *same* across projects):
+
+- **Namespaced streams** — `nq:{project}:{queue}` (+ `:cg`, `:dlq`) and
+  `nq:{project}:status`, so multiple projects/queues coexist on one Redis
+  (the default global `"taskiq"` stream is never used).
+- **Versioned envelope** — standard labels (`nq_v`, `nq_task`, `nq_tenant`,
+  `nq_idem`, `nq_trace`, `nq_enqueued_at`, `nq_priority`) on top of taskiq's
+  message, plus typed pydantic payloads.
+- **Ports** — `JobStatePort`, `BlobStorePort`, `IndexPort`, `StatusEventPort`.
+  Handlers depend only on these; each project supplies the adapters
+  (e.g. Payload vs Postgres/MinIO).
+- **Middleware stack** (broker-level): idempotency (dedup on `nq_idem`),
+  DLQ (dead-letter on retry-exhaustion instead of silent drop), retries with
+  exponential backoff + jitter, OTel tracing (`nq_trace` propagation), and
+  Prometheus metrics.
+- **Producer + kicker** — a Python `Publisher` and a generic HTTP kicker for
+  non-Python producers. The TypeScript producer client ships as
+  `@zetesis/nexus-queue`.
+
+Spec: `nexus-queue-spec.md`.
+
+Released via release-please on every conventional commit to `main`
+(scope `nexus-queue`).

nexus_queue-0.1.1/README.md

@@ -0,0 +1,29 @@
+# nexus-queue
+
+Portable worker runtime for the **Nexus-Queue** standard: taskiq + Redis Streams,
+domain-agnostic, ports-and-adapters. One project builds queues the same way as
+the next, and a worker's handlers move between projects unchanged.
+
+What this package owns (the parts that are the *same* across projects):
+
+- **Namespaced streams** — `nq:{project}:{queue}` (+ `:cg`, `:dlq`) and
+  `nq:{project}:status`, so multiple projects/queues coexist on one Redis
+  (the default global `"taskiq"` stream is never used).
+- **Versioned envelope** — standard labels (`nq_v`, `nq_task`, `nq_tenant`,
+  `nq_idem`, `nq_trace`, `nq_enqueued_at`, `nq_priority`) on top of taskiq's
+  message, plus typed pydantic payloads.
+- **Ports** — `JobStatePort`, `BlobStorePort`, `IndexPort`, `StatusEventPort`.
+  Handlers depend only on these; each project supplies the adapters
+  (e.g. Payload vs Postgres/MinIO).
+- **Middleware stack** (broker-level): idempotency (dedup on `nq_idem`),
+  DLQ (dead-letter on retry-exhaustion instead of silent drop), retries with
+  exponential backoff + jitter, OTel tracing (`nq_trace` propagation), and
+  Prometheus metrics.
+- **Producer + kicker** — a Python `Publisher` and a generic HTTP kicker for
+  non-Python producers. The TypeScript producer client ships as
+  `@zetesis/nexus-queue`.
+
+Spec: `nexus-queue-spec.md`.
+
+Released via release-please on every conventional commit to `main`
+(scope `nexus-queue`).

nexus_queue-0.1.1/nexus_queue/__init__.py

@@ -0,0 +1,86 @@
+"""nexus-queue — portable taskiq + Redis Streams worker runtime.
+
+Public API is intentionally small and stable: the config, the ports, the
+envelope, and the error taxonomy. The runtime pieces (broker, middleware,
+publisher, kicker) are added on top of these and re-exported as they land.
+"""
+
+from __future__ import annotations
+
+from nexus_queue.app import WorkerApp, create_worker
+from nexus_queue.broker import create_broker
+from nexus_queue.config import RuntimeConfig
+from nexus_queue.delayed import DelayedRetryPoller
+from nexus_queue.envelope import (
+    Envelope,
+    missing_required_labels,
+    require_supported_version,
+)
+from nexus_queue.exceptions import (
+    NexusPermanentError,
+    NexusQueueError,
+    NexusRetryableError,
+)
+from nexus_queue.handlers import HandlerSpec, register
+from nexus_queue.kicker import create_kicker
+from nexus_queue.lifecycle import (
+    IdempotencyStore,
+    configure_logging,
+    register_lifecycle,
+)
+from nexus_queue.naming import (
+    NQ_VERSION,
+    SINGLE_TENANT,
+    consumer_group,
+    delayed_set,
+    dlq_stream,
+    status_stream,
+    work_stream,
+)
+from nexus_queue.pipeline import PipelineRouter
+from nexus_queue.ports import (
+    BlobStorePort,
+    IndexPort,
+    JobStatePort,
+    JobStatus,
+    StatusEvent,
+    StatusEventPort,
+)
+from nexus_queue.publisher import Publisher
+from nexus_queue.tracing import configure_tracing
+
+__all__ = [
+    "NQ_VERSION",
+    "SINGLE_TENANT",
+    "BlobStorePort",
+    "DelayedRetryPoller",
+    "Envelope",
+    "HandlerSpec",
+    "IdempotencyStore",
+    "IndexPort",
+    "JobStatePort",
+    "JobStatus",
+    "NexusPermanentError",
+    "NexusQueueError",
+    "NexusRetryableError",
+    "PipelineRouter",
+    "Publisher",
+    "RuntimeConfig",
+    "StatusEvent",
+    "StatusEventPort",
+    "WorkerApp",
+    "configure_logging",
+    "configure_tracing",
+    "consumer_group",
+    "create_broker",
+    "create_kicker",
+    "create_worker",
+    "delayed_set",
+    "dlq_stream",
+    "missing_required_labels",
+    "register",
+    "register_lifecycle",
+    "require_supported_version",
+    "status_stream",
+    "work_stream",
+]

nexus_queue-0.1.1/nexus_queue/app.py

@@ -0,0 +1,47 @@
+"""Top-level factory. Consumers call ``create_worker(config, adapters, handlers)``
+and expose the returned ``broker`` to the taskiq CLI and ``app`` to uvicorn.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from taskiq import AsyncBroker
+
+from nexus_queue.broker import create_broker
+from nexus_queue.config import RuntimeConfig
+from nexus_queue.handlers import HandlerSpec, register
+from nexus_queue.kicker import create_kicker
+from nexus_queue.lifecycle import configure_logging, register_lifecycle
+from nexus_queue.tracing import configure_tracing
+
+
+@dataclass(slots=True, frozen=True)
+class WorkerApp:
+    """Bundle returned by :func:`create_worker`: ``app, broker = create_worker(...)``."""
+
+    app: FastAPI
+    broker: AsyncBroker
+
+    def __iter__(self) -> Iterator[FastAPI | AsyncBroker]:
+        yield self.app
+        yield self.broker
+
+
+def create_worker(
+    config: RuntimeConfig,
+    adapters: object,
+    handlers: Sequence[HandlerSpec],
+) -> WorkerApp:
+    """Build the broker (namespaced + middleware), register lifecycle + handlers,
+    and wrap a FastAPI kicker."""
+    configure_logging(config)
+    configure_tracing(config)
+    broker = create_broker(config)
+    register_lifecycle(broker, config, adapters)
+    for spec in handlers:
+        register(broker, spec, config)
+    app = create_kicker(broker, config)
+    return WorkerApp(app=app, broker=broker)

nexus_queue-0.1.1/nexus_queue/broker.py

@@ -0,0 +1,29 @@
+"""Broker factory — the one place that builds a namespaced, middleware-wrapped broker.
+
+Consumers never instantiate ``RedisStreamBroker`` directly: that is how ZP and
+nixon ended up on the default global ``"taskiq"`` stream (which collides across
+projects). Here the stream and consumer group are always
+``nq:{project}:{queue}`` / ``…:cg``.
+"""
+
+from __future__ import annotations
+
+from taskiq import AsyncBroker
+from taskiq_redis import RedisStreamBroker
+
+from nexus_queue.config import RuntimeConfig
+from nexus_queue.middleware.metrics import MetricsMiddleware
+from nexus_queue.middleware.retry_dlq import RetryDlqMiddleware
+
+
+def create_broker(config: RuntimeConfig) -> AsyncBroker:
+    """Build the standard broker: namespaced streams + the Nexus-Queue middleware stack."""
+    broker: AsyncBroker = RedisStreamBroker(
+        url=config.redis_url,
+        queue_name=config.work_stream,
+        consumer_group_name=config.consumer_group,
+    )
+    return broker.with_middlewares(
+        MetricsMiddleware(config),
+        RetryDlqMiddleware(config),
+    )

nexus_queue-0.1.1/nexus_queue/config.py

@@ -0,0 +1,98 @@
+"""Runtime configuration consumed by the worker runtime.
+
+A single pydantic model filled in by the consumer. No env loading inside the
+library (mirrors `agno-agent-builder` / `payload-documents-worker-builder`) so a
+multi-tenant deploy can build several `RuntimeConfig` instances from one env.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, SecretStr, ValidationInfo, field_validator
+
+from nexus_queue import naming
+
+
+class RuntimeConfig(BaseModel):
+    """Everything the runtime needs that is not a port adapter or a handler."""
+
+    app_name: str = Field(
+        description="FastAPI title and structlog identity; shows up in logs and /health.",
+    )
+
+    # ── Identity / namespacing ─────────────────────────────────────────────
+    project: str = Field(
+        description="Stable short project slug used to namespace streams, e.g. 'zp', 'nixon'.",
+    )
+    queue: str = Field(
+        description="Logical queue/pipeline name, e.g. 'documents', 'jobs'.",
+    )
+
+    # ── Broker ─────────────────────────────────────────────────────────────
+    redis_url: str = Field(
+        description="Redis URL for the taskiq-redis stream broker (e.g. redis://redis:6379).",
+    )
+
+    # ── HTTP kicker ────────────────────────────────────────────────────────
+    internal_secret: SecretStr = Field(
+        default=SecretStr(""),
+        description="Shared secret required by the kicker (X-Nexus-Secret). Empty disables the kicker auth gate.",
+    )
+    public_paths: tuple[str, ...] = Field(
+        default=("/health", "/ready", "/metrics", "/docs", "/openapi.json"),
+        description="Kicker paths served without the secret.",
+    )
+
+    # ── Retry / DLQ / idempotency ──────────────────────────────────────────
+    max_retries: int = Field(
+        default=3,
+        ge=0,
+        description="Retry attempts before a message is dead-lettered.",
+    )
+    retry_base_delay_s: float = Field(
+        default=2.0,
+        gt=0,
+        description="Base delay for the exponential backoff applied between retries.",
+    )
+    retry_poll_interval_s: float = Field(
+        default=1.0,
+        gt=0,
+        description="How often the delayed-retry poller drains due retries back onto the work stream.",
+    )
+    idempotency_ttl_s: int = Field(
+        default=86_400,
+        ge=0,
+        description="TTL of the dedup key; 0 disables the idempotency middleware.",
+    )
+    dlq_maxlen: int = Field(
+        default=100_000,
+        ge=0,
+        description="Approx MAXLEN for the dead-letter stream; 0 = unbounded.",
+    )
+
+    # ── Logging ────────────────────────────────────────────────────────────
+    log_level: str = Field(default="INFO")
+
+    @field_validator("project", "queue")
+    @classmethod
+    def _validate_slug(cls, value: str, info: ValidationInfo) -> str:
+        return naming.validate_slug(value, kind=info.field_name or "slug")
+
+    @property
+    def work_stream(self) -> str:
+        return naming.work_stream(self.project, self.queue)
+
+    @property
+    def consumer_group(self) -> str:
+        return naming.consumer_group(self.project, self.queue)
+
+    @property
+    def dlq_stream(self) -> str:
+        return naming.dlq_stream(self.project, self.queue)
+
+    @property
+    def delayed_set(self) -> str:
+        return naming.delayed_set(self.project, self.queue)
+
+    @property
+    def status_stream(self) -> str:
+        return naming.status_stream(self.project)

nexus_queue-0.1.1/nexus_queue/delayed.py

@@ -0,0 +1,91 @@
+"""Delayed-retry queue: hold a failed message until its backoff elapses, then
+re-enqueue it.
+
+Redis Streams deliver immediately, so a backed-off retry can't ride the work
+stream. :class:`~nexus_queue.middleware.retry_dlq.RetryDlqMiddleware` parks the
+message in a sorted set scored by its due time; the :class:`DelayedRetryPoller`
+(started by the worker lifecycle) drains due messages back onto the broker. The
+atomic ``ZREM`` makes the move safe across worker replicas — only the one that
+removes a member re-enqueues it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import time
+from typing import Any
+
+import redis.asyncio as aioredis
+import structlog
+from taskiq import AsyncBroker
+from taskiq.kicker import AsyncKicker
+from taskiq.message import TaskiqMessage
+
+from nexus_queue.config import RuntimeConfig
+
+logger = structlog.get_logger("nexus_queue.delayed")
+
+
+def pack_retry(message: TaskiqMessage, labels: dict[str, Any]) -> str:
+    """Serialize a message (with its updated labels) for the delayed-retry set."""
+    return json.dumps(
+        {
+            "task_name": message.task_name,
+            "task_id": message.task_id,
+            "labels": labels,
+            "args": message.args,
+            "kwargs": message.kwargs,
+        }
+    )
+
+
+class DelayedRetryPoller:
+    """Moves due retries from the delayed sorted set back onto the broker."""
+
+    def __init__(self, broker: AsyncBroker, config: RuntimeConfig) -> None:
+        self._broker = broker
+        self._config = config
+        self._redis: aioredis.Redis | None = None
+        self._task: asyncio.Task[None] | None = None
+
+    async def startup(self) -> None:
+        self._redis = aioredis.from_url(self._config.redis_url)
+        self._task = asyncio.create_task(self._run())
+
+    async def shutdown(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+        if self._redis is not None:
+            await self._redis.aclose()
+
+    async def _run(self) -> None:
+        while True:
+            try:
+                await self._drain_due()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("delayed-poll-failed")
+            await asyncio.sleep(self._config.retry_poll_interval_s)
+
+    async def _drain_due(self) -> None:
+        if self._redis is None:
+            return
+        due = await self._redis.zrangebyscore(self._config.delayed_set, "-inf", time.time())
+        for record in due:
+            # Atomic claim: only the replica that removes the member re-enqueues it.
+            if await self._redis.zrem(self._config.delayed_set, record) == 1:
+                await self._reenqueue(json.loads(record))
+
+    async def _reenqueue(self, data: dict[str, Any]) -> None:
+        kicker: AsyncKicker[Any, Any] = AsyncKicker(
+            task_name=data["task_name"],
+            broker=self._broker,
+            labels=data["labels"],
+        ).with_task_id(data["task_id"])
+        await kicker.kiq(*data["args"], **data["kwargs"])
+        logger.info("retry-reenqueued", task=data["task_name"])

nexus_queue-0.1.1/nexus_queue/envelope.py

@@ -0,0 +1,56 @@
+"""The Nexus-Queue envelope: standard labels stamped on every message.
+
+Producers build an :class:`Envelope` and turn it into the ``labels`` dict that
+rides on the taskiq message; consumers validate the version on receipt.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from nexus_queue import naming
+from nexus_queue.exceptions import NexusPermanentError
+
+
+@dataclass(slots=True)
+class Envelope:
+    """Routing/metadata for a single enqueue. Carried in message labels, not args."""
+
+    task: str
+    tenant: str = naming.SINGLE_TENANT
+    idempotency_key: str | None = None
+    trace: str | None = None
+    priority: str = "default"
+
+    def to_labels(self) -> dict[str, str]:
+        """Render the standard labels. ``nq_enqueued_at`` is stamped now (UTC)."""
+        labels: dict[str, str] = {
+            naming.LABEL_VERSION: naming.NQ_VERSION,
+            naming.LABEL_TASK: self.task,
+            naming.LABEL_TENANT: self.tenant,
+            naming.LABEL_ENQUEUED_AT: datetime.now(UTC).isoformat(),
+            naming.LABEL_PRIORITY: self.priority,
+        }
+        if self.idempotency_key:
+            labels[naming.LABEL_IDEM] = self.idempotency_key
+        if self.trace:
+            labels[naming.LABEL_TRACE] = self.trace
+        return labels
+
+
+def require_supported_version(labels: Mapping[str, Any]) -> None:
+    """Raise :class:`NexusPermanent` (→ DLQ) if the message is a version we
+    don't speak. Keeps a future ``nq_v=2`` from being silently mishandled."""
+    version = str(labels.get(naming.LABEL_VERSION, ""))
+    if version != naming.NQ_VERSION:
+        raise NexusPermanentError(
+            f"Unsupported nq_v={version!r}; this worker speaks {naming.NQ_VERSION!r}"
+        )
+
+
+def missing_required_labels(labels: Mapping[str, Any]) -> tuple[str, ...]:
+    """Return the required labels absent from ``labels`` (empty tuple if valid)."""
+    return tuple(key for key in naming.REQUIRED_LABELS if not labels.get(key))

nexus_queue-0.1.1/nexus_queue/exceptions.py

@@ -0,0 +1,15 @@
+"""Error taxonomy that drives the runtime's retry vs dead-letter decision."""
+
+from __future__ import annotations
+
+
+class NexusQueueError(Exception):
+    """Base class for every error raised by nexus-queue."""
+
+
+class NexusRetryableError(NexusQueueError):
+    """Transient failure — retry until attempts are exhausted, then dead-letter."""
+
+
+class NexusPermanentError(NexusQueueError):
+    """Non-retryable failure — route straight to the DLQ, skip remaining retries."""

nexus_queue-0.1.1/nexus_queue/handlers.py

@@ -0,0 +1,80 @@
+"""Handler registration with the cross-cutting concerns that need an ``around``
+scope (which taskiq middleware hooks can't give): idempotency, tracing, latency.
+
+A handler is ``async def h(payload, deps) -> None`` — it depends only on its
+typed payload and the project's :class:`NexusAdapters`. ``register`` wraps it
+so the same handler runs unchanged in any project.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+from opentelemetry import trace
+from opentelemetry.propagate import extract
+from pydantic import BaseModel
+from taskiq import AsyncBroker, Context, TaskiqDepends
+
+from nexus_queue.config import RuntimeConfig
+from nexus_queue.envelope import require_supported_version
+from nexus_queue.lifecycle import IdempotencyStore
+from nexus_queue.middleware.metrics import CONSUME_SECONDS
+from nexus_queue.naming import LABEL_IDEM, LABEL_TENANT, LABEL_TRACE, SINGLE_TENANT
+
+logger = structlog.get_logger("nexus_queue.handlers")
+_tracer = trace.get_tracer("nexus_queue")
+
+# deps is the project's adapter container; the handler types it to a Protocol
+# of the ports it actually uses.
+HandlerFn = Callable[[Any, Any], Awaitable[None]]
+
+
+@dataclass(slots=True)
+class HandlerSpec:
+    """Binds a wire task name to a handler and its payload model."""
+
+    task_name: str
+    handler: HandlerFn
+    payload_model: type[BaseModel]
+    idempotent: bool = True
+
+
+def register(broker: AsyncBroker, spec: HandlerSpec, config: RuntimeConfig) -> None:
+    """Register ``spec.handler`` under its wire task name, wrapped with version
+    check, idempotency dedup, an OTel consume span, and a latency histogram."""
+
+    async def _run(context: Context = TaskiqDepends(), **kwargs: Any) -> None:
+        labels = context.message.labels
+        require_supported_version(labels)
+        state = context.state
+
+        raw_idem = labels.get(LABEL_IDEM) if spec.idempotent else None
+        idem = str(raw_idem) if raw_idem else None
+        store: IdempotencyStore | None = state.nexus_idempotency if idem else None
+        if store is not None and idem and await store.already_processed(idem):
+            logger.info("duplicate-skipped", task=spec.task_name, idem=idem)
+            return
+
+        adapters = state.nexus_adapters
+        payload = spec.payload_model(**kwargs)
+
+        traceparent = labels.get(LABEL_TRACE)
+        parent = extract({"traceparent": str(traceparent)}) if traceparent else None
+        with _tracer.start_as_current_span(
+            f"nexus_queue.consume {spec.task_name}",
+            context=parent,
+        ) as span:
+            span.set_attribute("nq.task", spec.task_name)
+            span.set_attribute("nq.tenant", str(labels.get(LABEL_TENANT, SINGLE_TENANT)))
+            with CONSUME_SECONDS.labels(config.project, config.queue, spec.task_name).time():
+                await spec.handler(payload, adapters)
+
+        # Record dedup only after success: a failed attempt must stay retryable.
+        if store is not None and idem:
+            await store.mark_processed(idem)
+
+    _run.__name__ = "nexus_run_" + spec.task_name.replace(".", "_").replace(":", "_")
+    broker.task(task_name=spec.task_name)(_run)