babelqueue 0.3.0__tar.gz → 0.5.0__tar.gz

{babelqueue-0.3.0 → babelqueue-0.5.0}/.github/workflows/ci.yml

@@ -24,10 +24,10 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
 
-      - name: Install
+      - name: Install (with Celery + Django adapters)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e ".[dev,celery,django]"
 
       - name: Run tests
         run: pytest

{babelqueue-0.3.0 → babelqueue-0.5.0}/CHANGELOG.md

@@ -9,6 +9,30 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-06
+
+### Added
+- **Celery adapter** (`babelqueue.celery`, `[celery]` extra) — `from_celery(app)`
+  builds a `BabelQueue` runtime on a Celery app's broker, and `install_worker(app)`
+  registers a Celery worker bootstep that drains URN-routed polyglot messages in a
+  background thread alongside Celery's own consumer.
+- **Django adapter** (`babelqueue.django`, `[django]` extra) — settings-driven
+  `BABELQUEUE` config, `get_app()` / `publish()` shortcuts, and a
+  `manage.py babelqueue_worker` management command. Add `"babelqueue.django"` to
+  `INSTALLED_APPS`.
+- Both adapters lazy-import their framework, so the core stays dependency-free.
+
+## [0.4.0] - 2026-06-06
+
+### Added
+- `EnvelopeCodec.urn()` — resolve the URN (`job`, accepting `urn` as an alias).
+- `EnvelopeCodec.accepts()` — consumer-side envelope validation (rejects empty URN,
+  unsupported `meta.schema_version`, blank `trace_id`, non-object `data`).
+- Shared **cross-SDK conformance suite** under `tests/conformance/` (vendored from
+  the canonical `conformance/` set) plus a `test_conformance.py` runner.
+
+## [0.3.0] - 2026-06-06
+
 ### Added
 - **RabbitMQ transport** (`PikaTransport`, `amqp://`): durable queue, persistent
   delivery, `basic_get` + manual ack, and the contract AMQP properties (`type`=URN,
@@ -44,6 +68,9 @@ The envelope wire format is versioned separately by `meta.schema_version`
 - Pre-1.0: the public API may change before the `1.0.0` tag.
 - The core has **zero runtime dependencies** (standard library only); Python `>=3.9`.
 
-[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/BabelQueue/babelqueue-python/releases/tag/v0.1.0

{babelqueue-0.3.0 → babelqueue-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 0.3.0
+Version: 0.5.0
 Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
 Project-URL: Homepage, https://babelqueue.com
 Project-URL: Source, https://github.com/BabelQueue/babelqueue-python
@@ -24,8 +24,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Provides-Extra: amqp
 Requires-Dist: pika>=1.3; extra == 'amqp'
+Provides-Extra: celery
+Requires-Dist: celery>=5; extra == 'celery'
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: redis
 Requires-Dist: redis>=4; extra == 'redis'
 Description-Content-Type: text/markdown
@@ -150,13 +154,51 @@ app.run()                               # consume forever (Ctrl-C to stop)
   `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
   tests/local). Bring your own by passing `transport=...`.
 
-> **Celery** / **Django** adapters are the next iterations.
+## Framework adapters — Celery & Django
+
+**Celery** (`pip install "babelqueue[celery]"`) — reuse your Celery app's broker for
+polyglot interop, and consume inbound messages as a Celery worker bootstep:
+
+```python
+from babelqueue.celery import from_celery, install_worker
+
+bq = from_celery(celery_app, queue="orders")    # runtime on Celery's broker
+bq.publish("urn:babel:orders:created", {"order_id": 1042})
+
+@bq.handler("urn:babel:orders:created")
+def on_created(data, meta): ...
+
+install_worker(celery_app, bq)                   # `celery worker` also drains URN messages
+```
+
+**Django** (`pip install "babelqueue[django]"`) — add `"babelqueue.django"` to
+`INSTALLED_APPS` and configure a `BABELQUEUE` dict:
+
+```python
+# settings.py
+BABELQUEUE = {"broker_url": "redis://localhost:6379/0", "queue": "orders", "dead_letter": True}
+```
+
+```python
+from babelqueue.django import publish, get_app
+
+publish("urn:babel:orders:created", {"order_id": 1042})   # in a view / signal
+
+@get_app().handler("urn:babel:orders:created")            # register handlers at startup
+def on_created(data, meta): ...
+```
+
+```bash
+python manage.py babelqueue_worker --queue orders          # run the consumer
+```
 
 ## What's here
 
-The codec/contracts/dead-letter (zero-dep core) **and** the `BabelQueue` runtime
-above (in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`). For
-framework integration, the Celery and Django adapters are planned.
+The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime
+(in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`), and framework
+adapters for **Celery** (`[celery]`) and **Django** (`[django]`). Every layer
+speaks the one canonical envelope, so it interoperates with the PHP/Laravel,
+Symfony, Go, Node and .NET SDKs.
 
 ## Testing
 

{babelqueue-0.3.0 → babelqueue-0.5.0}/README.md

@@ -118,13 +118,51 @@ app.run()                               # consume forever (Ctrl-C to stop)
   `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
   tests/local). Bring your own by passing `transport=...`.
 
-> **Celery** / **Django** adapters are the next iterations.
+## Framework adapters — Celery & Django
+
+**Celery** (`pip install "babelqueue[celery]"`) — reuse your Celery app's broker for
+polyglot interop, and consume inbound messages as a Celery worker bootstep:
+
+```python
+from babelqueue.celery import from_celery, install_worker
+
+bq = from_celery(celery_app, queue="orders")    # runtime on Celery's broker
+bq.publish("urn:babel:orders:created", {"order_id": 1042})
+
+@bq.handler("urn:babel:orders:created")
+def on_created(data, meta): ...
+
+install_worker(celery_app, bq)                   # `celery worker` also drains URN messages
+```
+
+**Django** (`pip install "babelqueue[django]"`) — add `"babelqueue.django"` to
+`INSTALLED_APPS` and configure a `BABELQUEUE` dict:
+
+```python
+# settings.py
+BABELQUEUE = {"broker_url": "redis://localhost:6379/0", "queue": "orders", "dead_letter": True}
+```
+
+```python
+from babelqueue.django import publish, get_app
+
+publish("urn:babel:orders:created", {"order_id": 1042})   # in a view / signal
+
+@get_app().handler("urn:babel:orders:created")            # register handlers at startup
+def on_created(data, meta): ...
+```
+
+```bash
+python manage.py babelqueue_worker --queue orders          # run the consumer
+```
 
 ## What's here
 
-The codec/contracts/dead-letter (zero-dep core) **and** the `BabelQueue` runtime
-above (in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`). For
-framework integration, the Celery and Django adapters are planned.
+The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime
+(in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`), and framework
+adapters for **Celery** (`[celery]`) and **Django** (`[django]`). Every layer
+speaks the one canonical envelope, so it interoperates with the PHP/Laravel,
+Symfony, Go, Node and .NET SDKs.
 
 ## Testing
 

{babelqueue-0.3.0 → babelqueue-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "0.3.0"
+version = "0.5.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -28,9 +28,11 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-# Planned runtime / adapters — standard, zero-heavy-dep drivers.
+# Optional runtime drivers + framework adapters — standard, zero-heavy-dep.
 redis = ["redis>=4"]
 amqp = ["pika>=1.3"]
+celery = ["celery>=5"]
+django = ["django>=4.2"]
 dev = ["pytest>=7"]
 
 [project.urls]

{babelqueue-0.3.0 → babelqueue-0.5.0}/src/babelqueue/__init__.py

@@ -19,7 +19,7 @@ from .exceptions import BabelQueueError, UnknownUrnError
 from .routing import UnknownUrnStrategy
 from .transport import InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "BabelQueue",

babelqueue-0.5.0/src/babelqueue/celery.py

@@ -0,0 +1,88 @@
+"""Celery integration. Requires the ``celery`` extra:
+
+    pip install "babelqueue[celery]"
+
+A Celery app already configures a broker (Redis/RabbitMQ). :func:`from_celery`
+builds a :class:`~babelqueue.BabelQueue` runtime on that *same* broker, so a
+Celery-based service produces and consumes the canonical polyglot envelope
+alongside its Celery tasks — interoperating with the PHP/Laravel, Go, Node, ...
+SDKs. :func:`install_worker` runs that consumer as a Celery worker *bootstep* (a
+daemon thread started on ``celery worker``), so one process handles both Celery
+tasks and inbound polyglot messages.
+
+``celery`` is imported lazily, so the core stays dependency-free.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Optional
+
+from .app import BabelQueue
+from .exceptions import BabelQueueError
+
+
+def broker_url(celery_app: Any) -> str:
+    """Extract the broker URL from a Celery app (supports old/new config keys)."""
+    conf = getattr(celery_app, "conf", None)
+    url = None
+    if conf is not None:
+        url = getattr(conf, "broker_url", None)
+        if not url and hasattr(conf, "get"):
+            url = conf.get("broker_url") or conf.get("BROKER_URL")
+    if not url:
+        raise BabelQueueError(
+            "The Celery app has no broker configured; set broker_url before calling from_celery()."
+        )
+    return str(url)
+
+
+def from_celery(celery_app: Any, **kwargs: Any) -> BabelQueue:
+    """Build a :class:`~babelqueue.BabelQueue` runtime on the Celery app's broker.
+
+    Extra keyword arguments are forwarded to ``BabelQueue`` (``queue``,
+    ``max_attempts``, ``dead_letter``, ``on_unknown_urn``, ...).
+    """
+    return BabelQueue(broker_url(celery_app), **kwargs)
+
+
+def install_worker(
+    celery_app: Any,
+    babel_app: Optional[BabelQueue] = None,
+    *,
+    queue: Optional[str] = None,
+    **kwargs: Any,
+) -> type:
+    """Register a Celery worker bootstep that consumes BabelQueue messages.
+
+    When a ``celery worker`` boots, the step starts a daemon thread running the
+    BabelQueue consumer loop (URN routing, retry → dead-letter). If ``babel_app``
+    is omitted it is built with :func:`from_celery`. Returns the bootstep class.
+    """
+    from celery import bootsteps  # lazy: only needed for this integration
+
+    app = babel_app if babel_app is not None else from_celery(celery_app, **kwargs)
+
+    class BabelQueueConsumerStep(bootsteps.StartStopStep):
+        """Runs the BabelQueue consumer loop alongside Celery's own consumer."""
+
+        def __init__(self, parent: Any, **options: Any) -> None:
+            super().__init__(parent, **options)
+            self._thread: Optional[threading.Thread] = None
+            self._stop = threading.Event()
+
+        def start(self, parent: Any) -> None:
+            def loop() -> None:
+                while not self._stop.is_set():
+                    app.consume(queue, max_messages=1, timeout=1.0)
+
+            self._thread = threading.Thread(
+                target=loop, name="babelqueue-consumer", daemon=True
+            )
+            self._thread.start()
+
+        def stop(self, parent: Any) -> None:
+            self._stop.set()
+
+    celery_app.steps["worker"].add(BabelQueueConsumerStep)
+    return BabelQueueConsumerStep

{babelqueue-0.3.0 → babelqueue-0.5.0}/src/babelqueue/codec.py

@@ -94,3 +94,36 @@ class EnvelopeCodec:
         except (ValueError, TypeError):
             return {}
         return decoded if isinstance(decoded, dict) else {}
+
+    @staticmethod
+    def urn(envelope: Mapping[str, Any]) -> str:
+        """The message URN: canonical ``job``, with ``urn`` accepted as an alias."""
+        return str(envelope.get("job") or envelope.get("urn") or "")
+
+    @staticmethod
+    def accepts(envelope: Mapping[str, Any]) -> bool:
+        """Whether a consumer should accept this envelope (consumer-side validation).
+
+        Rejects messages with no URN, an unsupported ``meta.schema_version``, a
+        missing/blank ``trace_id``, or a non-object ``data`` / non-integer
+        ``attempts``. (Accepts the ``urn`` alias, unlike the producer JSON Schema.)
+        """
+        if EnvelopeCodec.urn(envelope) == "":
+            return False
+
+        meta = envelope.get("meta")
+        if not isinstance(meta, dict) or meta.get("schema_version") != SCHEMA_VERSION:
+            return False
+
+        if not isinstance(envelope.get("data"), dict):
+            return False
+
+        attempts = envelope.get("attempts")
+        if not isinstance(attempts, int) or isinstance(attempts, bool):
+            return False
+
+        trace_id = envelope.get("trace_id")
+        if not isinstance(trace_id, str) or trace_id == "":
+            return False
+
+        return True

babelqueue-0.5.0/src/babelqueue/django/__init__.py

@@ -0,0 +1,72 @@
+"""Django integration. Requires the ``django`` extra:
+
+    pip install "babelqueue[django]"
+
+Add ``"babelqueue.django"`` to ``INSTALLED_APPS`` and configure a ``BABELQUEUE``
+settings dict::
+
+    BABELQUEUE = {
+        "broker_url": "redis://localhost:6379/0",
+        "queue": "orders",
+        "max_attempts": 3,
+        "dead_letter": True,
+    }
+
+Then publish from views/signals with :func:`publish`, register handlers on
+:func:`get_app`, and run the consumer with ``python manage.py babelqueue_worker``.
+The runtime is the shared :class:`~babelqueue.BabelQueue`, so messages interoperate
+with the PHP/Laravel, Go, Node, ... SDKs. ``django`` is imported lazily.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from ..app import BabelQueue
+
+# Keys (besides broker_url) forwarded to the BabelQueue constructor.
+_APP_KWARGS = frozenset(
+    {
+        "queue",
+        "on_unknown_urn",
+        "max_attempts",
+        "dead_letter",
+        "dead_letter_queue",
+        "dead_letter_suffix",
+        "transport",
+    }
+)
+
+_app: Optional[BabelQueue] = None
+
+
+def _build() -> BabelQueue:
+    from django.conf import settings  # lazy
+
+    raw: Mapping[str, Any] = getattr(settings, "BABELQUEUE", {}) or {}
+    kwargs: Dict[str, Any] = {k: v for k, v in raw.items() if k in _APP_KWARGS}
+    broker = raw.get("broker_url", "memory://")
+    return BabelQueue(broker, **kwargs)
+
+
+def get_app() -> BabelQueue:
+    """Return the process-wide :class:`~babelqueue.BabelQueue`, built from
+    ``settings.BABELQUEUE`` on first use."""
+    global _app
+    if _app is None:
+        _app = _build()
+    return _app
+
+
+def publish(urn: str, data: Mapping[str, Any], **kwargs: Any) -> str:
+    """Publish a message through the configured app; returns its id (``meta.id``)."""
+    return get_app().publish(urn, dict(data), **kwargs)
+
+
+def reset() -> None:
+    """Drop the cached app so the next :func:`get_app` rebuilds it (tests / settings reload)."""
+    global _app
+    _app = None
+
+
+__all__ = ["get_app", "publish", "reset"]

babelqueue-0.5.0/src/babelqueue/django/apps.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class BabelQueueConfig(AppConfig):
+    """Django app config for the BabelQueue adapter."""
+
+    name = "babelqueue.django"
+    label = "babelqueue"
+    verbose_name = "BabelQueue"

babelqueue-0.5.0/src/babelqueue/django/management/commands/babelqueue_worker.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.management.base import BaseCommand
+
+from babelqueue.django import get_app
+
+
+class Command(BaseCommand):
+    help = "Run the BabelQueue consumer: routes inbound polyglot messages by URN."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--queue",
+            dest="queue",
+            default=None,
+            help="Queue to consume (default: the configured queue).",
+        )
+        parser.add_argument(
+            "--max-messages",
+            dest="max_messages",
+            type=int,
+            default=None,
+            help="Stop after N messages (default: run until interrupted).",
+        )
+        parser.add_argument(
+            "--timeout",
+            dest="timeout",
+            type=float,
+            default=1.0,
+            help="Per-poll block timeout in seconds (default: 1.0).",
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        app = get_app()
+        queue = options["queue"] or app.queue
+        self.stdout.write(f"BabelQueue consumer listening on '{queue}' …")
+        processed = app.consume(
+            options["queue"],
+            max_messages=options["max_messages"],
+            timeout=options["timeout"],
+        )
+        self.stdout.write(self.style.SUCCESS(f"Processed {processed} message(s)."))

babelqueue-0.5.0/tests/conformance/fixtures/invalid-missing-urn.json

@@ -0,0 +1,14 @@
+{
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-0.5.0/tests/conformance/fixtures/invalid-unknown-schema-version.json

@@ -0,0 +1,15 @@
+{
+  "job": "urn:babel:orders:created",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 2,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-0.5.0/tests/conformance/fixtures/unicode-and-numbers.json

@@ -0,0 +1,20 @@
+{
+  "job": "urn:babel:catalog:item.indexed",
+  "trace_id": "3f7a1d2e-9b4c-4a8d-bc1e-0f5a6b7c8d90",
+  "data": {
+    "title": "Café — naïve ☕",
+    "qty": 7,
+    "price_cents": 1299,
+    "ratio": 0.5,
+    "active": true,
+    "note": null
+  },
+  "meta": {
+    "id": "b2c3d4e5-f607-4890-a1b2-c3d4e5f60718",
+    "queue": "catalog",
+    "lang": "python",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 2
+}

babelqueue-0.5.0/tests/conformance/fixtures/urn-alias.json

@@ -0,0 +1,15 @@
+{
+  "urn": "urn:babel:orders:created",
+  "trace_id": "9c1e0b44-7a2d-4e6f-8a10-2b3c4d5e6f70",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "a1b2c3d4-e5f6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "go",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-0.5.0/tests/conformance/manifest.json

@@ -0,0 +1,71 @@
+{
+  "schema_version": 1,
+  "description": "Cross-SDK conformance cases. Every BabelQueue SDK core must satisfy these against the canonical wire envelope. Per-message fields (meta.id, trace_id, meta.created_at) are intrinsically unique and are NOT asserted by value.",
+  "cases": [
+    {
+      "name": "order-created",
+      "file": "fixtures/order-created.json",
+      "valid": true,
+      "description": "A normal produced envelope.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 0,
+        "lang": "php",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "urn-alias",
+      "file": "fixtures/urn-alias.json",
+      "valid": true,
+      "description": "Consumers MUST accept 'urn' as an inbound alias for 'job'.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 0,
+        "lang": "go",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "dead-lettered",
+      "file": "fixtures/dead-lettered.json",
+      "valid": true,
+      "description": "A dead-lettered message: original preserved + additive dead_letter block.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 3,
+        "lang": "php",
+        "schema_version": 1,
+        "dead_letter": { "reason": "failed", "original_queue": "orders" }
+      }
+    },
+    {
+      "name": "unicode-and-numbers",
+      "file": "fixtures/unicode-and-numbers.json",
+      "valid": true,
+      "description": "UTF-8 strings, integers, an exact float, boolean and null round-trip identically.",
+      "expect": {
+        "urn": "urn:babel:catalog:item.indexed",
+        "data": { "title": "Café — naïve ☕", "qty": 7, "price_cents": 1299, "ratio": 0.5, "active": true, "note": null },
+        "attempts": 2,
+        "lang": "python",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "invalid-unknown-schema-version",
+      "file": "fixtures/invalid-unknown-schema-version.json",
+      "valid": false,
+      "reason": "meta.schema_version is not a version this SDK supports"
+    },
+    {
+      "name": "invalid-missing-urn",
+      "file": "fixtures/invalid-missing-urn.json",
+      "valid": false,
+      "reason": "no 'job' or 'urn' — the message has no identity"
+    }
+  ]
+}

babelqueue-0.5.0/tests/conformance/schema/message-envelope.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://babelqueue.com/contracts/message-envelope.schema.json",
+  "title": "BabelQueueMessageEnvelope",
+  "description": "The canonical, language-agnostic BabelQueue wire envelope (schema_version 1). This schema is authoritative alongside contracts/message-envelope.md.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["job", "trace_id", "data", "meta", "attempts"],
+  "properties": {
+    "job": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The message URN — language-agnostic identity. Canonical producer field name. Consumers also accept 'urn' as an inbound alias. Never a class name.",
+      "examples": ["urn:babel:orders:created", "urn:babel:orders:invoice.requested"]
+    },
+    "urn": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Inbound alias for 'job'. Accepted by consumers for interoperability; producers SHOULD emit 'job'."
+    },
+    "trace_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Cross-service correlation id. Generated by the first producer, preserved and forwarded unchanged by every SDK across every hop."
+    },
+    "data": {
+      "type": "object",
+      "description": "Pure, JSON-encodable business payload. No language-specific types. Numbers/time/binary per contracts/message-envelope.md section 6.",
+      "additionalProperties": true
+    },
+    "meta": {
+      "type": "object",
+      "description": "Producer-set, immutable descriptive metadata.",
+      "additionalProperties": true,
+      "required": ["id", "queue", "lang", "schema_version", "created_at"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique id for THIS message (distinct from trace_id)."
+        },
+        "queue": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logical queue name (not the broker key)."
+        },
+        "lang": {
+          "type": "string",
+          "enum": ["php", "go", "python", "java", "dotnet", "node"],
+          "description": "Producer language tag."
+        },
+        "schema_version": {
+          "type": "integer",
+          "const": 1,
+          "description": "Envelope schema version. Consumers MUST reject versions they do not support."
+        },
+        "created_at": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Production time as Unix epoch MILLISECONDS, UTC."
+        }
+      }
+    },
+    "attempts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Top-level transport retry counter, mutated by the broker/worker. Deliberately kept OUT of the immutable meta block."
+    },
+    "dead_letter": {
+      "type": "object",
+      "description": "Optional. Present ONLY on messages sitting on a dead-letter queue (ADR-0009). Additive, so it does not change schema_version. Normal consumers ignore it.",
+      "additionalProperties": true,
+      "required": ["reason", "failed_at", "original_queue", "attempts"],
+      "properties": {
+        "reason": {
+          "type": "string",
+          "enum": ["failed", "unknown_urn", "poison"],
+          "description": "Why the message was dead-lettered."
+        },
+        "error": {
+          "type": ["string", "null"],
+          "description": "Human-readable error message, if any."
+        },
+        "exception": {
+          "type": ["string", "null"],
+          "description": "Producer-language exception/type name, if any (informational, language-specific)."
+        },
+        "failed_at": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Dead-letter time as Unix epoch milliseconds, UTC."
+        },
+        "original_queue": {
+          "type": "string",
+          "description": "The queue the message was consumed from before dead-lettering."
+        },
+        "attempts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delivery attempts made before dead-lettering."
+        },
+        "lang": {
+          "type": "string",
+          "enum": ["php", "go", "python", "java", "dotnet", "node"],
+          "description": "Language of the SDK that dead-lettered the message."
+        }
+      }
+    }
+  }
+}

babelqueue-0.5.0/tests/fixtures/dead-lettered.json

@@ -0,0 +1,24 @@
+{
+  "job": "urn:babel:orders:created",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 3,
+  "dead_letter": {
+    "reason": "failed",
+    "error": "Payment gateway timeout",
+    "exception": "App\\Exceptions\\GatewayTimeout",
+    "failed_at": 1749132730000,
+    "original_queue": "orders",
+    "attempts": 3,
+    "lang": "php"
+  }
+}

babelqueue-0.5.0/tests/fixtures/order-created.json

@@ -0,0 +1,15 @@
+{
+  "job": "urn:babel:orders:created",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-0.5.0/tests/test_celery.py

@@ -0,0 +1,68 @@
+"""Celery adapter — from_celery bridge + worker bootstep.
+
+Skips unless ``celery`` is installed (``pip install "babelqueue[celery]"``). Uses
+Celery's ``memory://`` broker, so no external broker is required.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+try:
+    import celery  # noqa: F401
+
+    HAS_CELERY = True
+except ImportError:
+    HAS_CELERY = False
+
+from babelqueue import BabelQueue, BabelQueueError
+
+
+@unittest.skipUnless(HAS_CELERY, "celery is not installed")
+class CeleryAdapterTest(unittest.TestCase):
+    def _celery_app(self):
+        from celery import Celery
+
+        return Celery("test", broker="memory://")
+
+    def test_from_celery_builds_runtime_on_the_celery_broker(self) -> None:
+        from babelqueue.celery import from_celery
+
+        app = from_celery(self._celery_app(), queue="orders")
+        self.assertIsInstance(app, BabelQueue)
+        self.assertEqual(app.queue, "orders")
+
+        seen = {}
+
+        @app.handler("urn:babel:orders:created")
+        def handle(data, meta):  # noqa: ANN001
+            seen["data"] = data
+
+        app.publish("urn:babel:orders:created", {"order_id": 1})
+        processed = app.consume(max_messages=1)
+
+        self.assertEqual(processed, 1)
+        self.assertEqual(seen["data"], {"order_id": 1})
+
+    def test_from_celery_requires_a_broker(self) -> None:
+        from celery import Celery
+
+        from babelqueue.celery import from_celery
+
+        app = Celery("test")  # no broker
+        app.conf.broker_url = None
+        with self.assertRaises(BabelQueueError):
+            from_celery(app)
+
+    def test_install_worker_registers_a_bootstep(self) -> None:
+        from babelqueue.celery import from_celery, install_worker
+
+        celery_app = self._celery_app()
+        babel = from_celery(celery_app)
+        step = install_worker(celery_app, babel)
+
+        self.assertIn(step, celery_app.steps["worker"])
+
+
+if __name__ == "__main__":
+    unittest.main()

babelqueue-0.5.0/tests/test_conformance.py

@@ -0,0 +1,58 @@
+"""Runs the shared cross-SDK conformance suite (vendored under tests/conformance/).
+
+The same manifest + fixtures are run by every BabelQueue SDK; passing here proves
+this SDK reads/writes the canonical envelope identically to the others.
+"""
+
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+
+from babelqueue import EnvelopeCodec
+
+SUITE = Path(__file__).parent / "conformance"
+MANIFEST = json.loads((SUITE / "manifest.json").read_text(encoding="utf-8"))
+
+
+class ConformanceTest(unittest.TestCase):
+    def test_suite_is_present(self) -> None:
+        self.assertEqual(MANIFEST["schema_version"], 1)
+        self.assertGreaterEqual(len(MANIFEST["cases"]), 6)
+
+    def test_cases(self) -> None:
+        for case in MANIFEST["cases"]:
+            with self.subTest(case=case["name"]):
+                raw = (SUITE / case["file"]).read_text(encoding="utf-8")
+                env = EnvelopeCodec.decode(raw)
+                self.assertNotEqual(env, {}, "fixture must decode")
+
+                if not case["valid"]:
+                    self.assertFalse(
+                        EnvelopeCodec.accepts(env),
+                        f"{case['name']} must be rejected: {case.get('reason')}",
+                    )
+                    continue
+
+                expect = case["expect"]
+                self.assertTrue(EnvelopeCodec.accepts(env), f"{case['name']} must be accepted")
+                self.assertEqual(EnvelopeCodec.urn(env), expect["urn"])
+                self.assertEqual(env["attempts"], expect["attempts"])
+                self.assertEqual(env["meta"]["lang"], expect["lang"])
+                self.assertEqual(env["meta"]["schema_version"], expect["schema_version"])
+
+                if "data" in expect:
+                    self.assertEqual(env["data"], expect["data"])
+
+                if "dead_letter" in expect:
+                    for key, value in expect["dead_letter"].items():
+                        self.assertEqual(env["dead_letter"][key], value)
+
+                # Per-message fields must be present (not asserted by value).
+                self.assertIn("id", env["meta"])
+                self.assertTrue(env["trace_id"])
+
+
+if __name__ == "__main__":
+    unittest.main()

babelqueue-0.5.0/tests/test_django.py

@@ -0,0 +1,67 @@
+"""Django adapter — settings-driven app, publish() shortcut, worker command.
+
+Skips unless ``django`` is installed (``pip install "babelqueue[django]"``). Uses
+the ``memory://`` transport, so no external broker is required.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+try:
+    import django  # noqa: F401
+
+    HAS_DJANGO = True
+except ImportError:
+    HAS_DJANGO = False
+
+
+@unittest.skipUnless(HAS_DJANGO, "django is not installed")
+class DjangoAdapterTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        import django
+        from django.conf import settings
+
+        if not settings.configured:
+            settings.configure(
+                INSTALLED_APPS=["babelqueue.django"],
+                BABELQUEUE={"broker_url": "memory://", "queue": "orders"},
+                LOGGING_CONFIG=None,
+            )
+            django.setup()
+
+    def setUp(self) -> None:
+        from babelqueue.django import reset
+
+        reset()
+
+    def test_get_app_reads_settings(self) -> None:
+        from babelqueue import BabelQueue
+        from babelqueue.django import get_app
+
+        app = get_app()
+        self.assertIsInstance(app, BabelQueue)
+        self.assertEqual(app.queue, "orders")
+
+    def test_publish_then_worker_command_processes_the_message(self) -> None:
+        from django.core.management import call_command
+
+        from babelqueue.django import get_app, publish
+
+        seen = {}
+
+        @get_app().handler("urn:babel:orders:created")
+        def handle(data, meta):  # noqa: ANN001
+            seen["data"] = data
+
+        msg_id = publish("urn:babel:orders:created", {"order_id": 9})
+        self.assertTrue(msg_id)
+
+        call_command("babelqueue_worker", "--max-messages=1")
+
+        self.assertEqual(seen["data"], {"order_id": 9})
+
+
+if __name__ == "__main__":
+    unittest.main()