babelqueue 0.5.0__tar.gz → 1.1.0__tar.gz

babelqueue-1.1.0/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# Shows a "Sponsor" button on this repository.
+github: muhammetsafak

babelqueue-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install (with Celery + Django adapters)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,celery,django]"
+
+      - name: Run tests
+        run: pytest
+
+  lint:
+    name: Static analysis (ruff + mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install (dev + all adapters for type context)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,celery,django,redis,amqp,sqs]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Mypy
+        run: mypy
+
+  integration:
+    name: Broker integration (Redis · RabbitMQ · SQS)
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+      rabbitmq:
+        image: rabbitmq:3
+        ports:
+          - 5672:5672
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 15
+      # Free, SQS-compatible broker for the SqsTransport round-trip. The native
+      # image is shell-less, so readiness is polled by a TCP-probe step below.
+      elasticmq:
+        image: softwaremill/elasticmq-native:1.6.11
+        ports:
+          - 9324:9324
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install (all adapters — full coverage with brokers)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[redis,amqp,sqs,celery,django,dev]"
+
+      - name: Wait for ElasticMQ
+        run: |
+          for i in $(seq 1 30); do
+            if (echo > /dev/tcp/localhost/9324) >/dev/null 2>&1; then
+              echo "ElasticMQ port 9324 open"; exit 0
+            fi
+            sleep 2
+          done
+          echo "ElasticMQ did not open port 9324"; exit 1
+
+      - name: Run full suite with coverage gate (>=90%)
+        env:
+          BABELQUEUE_TEST_REDIS: redis://localhost:6379/0
+          BABELQUEUE_TEST_AMQP: amqp://guest:guest@localhost:5672/
+          SQS_ENDPOINT: http://localhost:9324
+          AWS_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: test
+          AWS_SECRET_ACCESS_KEY: test
+        run: pytest --cov=babelqueue --cov-report=term-missing --cov-fail-under=90
+
+  conformance:
+    name: Conformance suite in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Verify vendored conformance matches the canonical suite
+        run: |
+          git clone --depth 1 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          diff -ru "$RUNNER_TEMP/conformance/manifest.json" "tests/conformance/manifest.json"
+          diff -ru "$RUNNER_TEMP/conformance/fixtures"      "tests/conformance/fixtures"
+          diff -ru "$RUNNER_TEMP/conformance/schema"        "tests/conformance/schema"
+          echo "Vendored conformance is in sync with the canonical suite."
+
+  ci-green:
+    name: CI green
+    runs-on: ubuntu-latest
+    needs: [test, lint, integration, conformance]
+    if: ${{ always() }}
+    steps:
+      - name: Fail if any required job did not pass
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}; then
+            echo "A required job failed or was cancelled."
+            exit 1
+          fi

{babelqueue-0.5.0 → babelqueue-1.1.0}/.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed
       contents: write   # create the GitHub release
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Setup Python
         uses: actions/setup-python@v5

{babelqueue-0.5.0 → babelqueue-1.1.0}/.gitignore

@@ -9,3 +9,6 @@ dist/
 .ruff_cache/
 .venv/
 venv/
+.coverage
+coverage.xml
+htmlcov/

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

@@ -7,7 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The envelope wire format is versioned separately by `meta.schema_version`
 (currently **1**) — see the contract at [babelqueue.com](https://babelqueue.com).
 
-## [Unreleased]
+## [1.1.0] - 2026-06-12
+
+### Added
+- **Amazon SQS transport** (`babelqueue[sqs]`, `boto3`) — `SqsTransport`, selected by
+  the `sqs://` URL scheme (e.g. `sqs://us-east-1?endpoint=http://localhost:4566` for
+  LocalStack). Implements [§3 of the broker-bindings contract](https://babelqueue.com):
+  the canonical envelope is the `MessageBody`, projected onto native `MessageAttributes`
+  (`bq-job`/`bq-trace-id`/`bq-message-id`/`bq-schema-version`/`bq-source-lang`/`bq-created-at`);
+  visibility-timeout reserve → `delete_message` ack; `attempts` reconciled to
+  `ApproximateReceiveCount − 1` (never lowering a runtime-incremented count). Supports
+  FIFO (`MessageGroupId`/`MessageDeduplicationId` = `meta.id`), content-based dedup,
+  configurable wait/visibility, and a `queue_url_prefix` that skips `GetQueueUrl`. A
+  client can be injected for tests/DI. 16 unit tests run against a fake client (no boto3,
+  no broker); a LocalStack integration test round-trips the real `boto3` path. The
+  envelope is unchanged (`schema_version: 1`); SQS is purely additive. Ships as a MINOR.
+
+## [1.0.0] - 2026-06-07
+
+**1.0.0 — the public API is now SemVer-stable**: breaking changes require a MAJOR,
+following the deprecation policy. The wire envelope is unchanged
+(`schema_version: 1`); the core + Celery/Django adapters ship together. Full
+reference at [babelqueue.com](https://babelqueue.com).
+
+### Internal
+- CI adds **ruff** + **mypy** static analysis and a **>=90% coverage gate**
+  (`pytest --cov --cov-fail-under=90`, run in the broker-backed job so the Redis /
+  RabbitMQ transports count). Type-safety fix in `redis_transport` (str-narrow the
+  BLMOVE reply) surfaced by mypy — no behaviour change.
+- **GR-8 latency benchmark** (`tests/test_overhead.py`) — asserts the envelope
+  encode/decode path adds **≤2%** over plain-JSON serialization vs a conservative
+  2ms broker round-trip (the pure-Python codec is slower than the compiled SDKs —
+  ~16µs marginal on CPython 3.9/CI — so the reference is higher to stay robust).
 
 ## [0.5.0] - 2026-06-06
 
@@ -68,7 +99,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.5.0...HEAD
+[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/BabelQueue/babelqueue-python/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.5.0...v1.0.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 0.5.0
+Version: 1.1.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
@@ -27,11 +27,16 @@ Requires-Dist: pika>=1.3; extra == 'amqp'
 Provides-Extra: celery
 Requires-Dist: celery>=5; extra == 'celery'
 Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: redis
 Requires-Dist: redis>=4; extra == 'redis'
+Provides-Extra: sqs
+Requires-Dist: boto3>=1.26; extra == 'sqs'
 Description-Content-Type: text/markdown
 
 # BabelQueue for Python

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "0.5.0"
+version = "1.1.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"
@@ -31,9 +31,10 @@ dependencies = []
 # Optional runtime drivers + framework adapters — standard, zero-heavy-dep.
 redis = ["redis>=4"]
 amqp = ["pika>=1.3"]
+sqs = ["boto3>=1.26"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
-dev = ["pytest>=7"]
+dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]
 
 [project.urls]
 Homepage = "https://babelqueue.com"
@@ -43,3 +44,21 @@ Changelog = "https://github.com/BabelQueue/babelqueue-python/blob/main/CHANGELOG
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/babelqueue"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.mypy]
+# Lowest target mypy accepts; the package itself still supports Python 3.9 at
+# runtime (requires-python >=3.9) and uses only 3.9-compatible typing.
+python_version = "3.10"
+files = ["src/babelqueue"]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+source = ["babelqueue"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = ["pragma: no cover", "raise NotImplementedError", "if TYPE_CHECKING:"]

{babelqueue-0.5.0 → babelqueue-1.1.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.5.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "BabelQueue",

{babelqueue-0.5.0 → babelqueue-1.1.0}/src/babelqueue/redis_transport.py

@@ -36,10 +36,15 @@ class RedisTransport(Transport):
         self._redis.rpush(queue, body)
 
     def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
-        body = self._redis.blmove(queue, self._processing(queue), timeout, "LEFT", "RIGHT")
+        # redis-py types the BLMOVE timeout as int, but Redis accepts a float
+        # (sub-second) timeout; passing it through is correct at runtime.
+        body = self._redis.blmove(queue, self._processing(queue), timeout, "LEFT", "RIGHT")  # type: ignore[arg-type]
         if body is None:
             return None
-        return ReceivedMessage(body=body, queue=queue, handle=body)
+        # decode_responses=True yields str; the guard satisfies the type checker
+        # (and is a harmless safety net otherwise).
+        text = body if isinstance(body, str) else body.decode()
+        return ReceivedMessage(body=text, queue=queue, handle=text)
 
     def ack(self, message: ReceivedMessage) -> None:
         self._redis.lrem(self._processing(message.queue), 1, message.handle)

babelqueue-1.1.0/src/babelqueue/sqs_transport.py

@@ -0,0 +1,209 @@
+"""Amazon SQS transport. Requires the ``sqs`` extra:
+
+    pip install "babelqueue[sqs]"
+
+Producing sends the canonical envelope as the message body and projects the
+contract envelope fields onto native SQS ``MessageAttributes`` (``bq-job`` = URN,
+``bq-trace-id`` = trace_id, ``bq-message-id`` = meta.id, plus ``bq-schema-version`` /
+``bq-source-lang`` / ``bq-created-at``) — so a Go/PHP/... peer can route on ``bq-job``
+and correlate on ``bq-trace-id`` without parsing the body. Consuming uses the
+visibility-timeout reservation model (``receive_message`` -> process ->
+``delete_message``); the authoritative attempt count is the broker's
+``ApproximateReceiveCount``, reconciled onto the envelope as ``attempts = count - 1``.
+
+This implements §3 of the broker-bindings contract. The envelope is unchanged
+(``schema_version`` stays 1); SQS is purely additive.
+
+URL form: ``sqs://[region][?endpoint=...&prefix=...&fifo=1&group_id=...&wait_time=20]``
+(e.g. ``sqs://us-east-1?endpoint=http://localhost:4566`` for LocalStack). Credentials
+come from the standard AWS default provider chain. For richer setups, build the
+transport directly and pass it via ``BabelQueue(transport=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlsplit
+
+from .codec import EnvelopeCodec
+from .transport import ReceivedMessage, Transport
+
+
+class SqsTransport(Transport):
+    def __init__(
+        self,
+        url: str = "sqs://",
+        *,
+        client: Any = None,
+        region: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        queue_url_prefix: Optional[str] = None,
+        wait_time: Optional[int] = None,
+        visibility_timeout: Optional[int] = None,
+        fifo: bool = False,
+        message_group_id: Optional[str] = None,
+        content_dedup: bool = False,
+    ) -> None:
+        parts = urlsplit(url) if url else urlsplit("sqs://")
+        q = parse_qs(parts.query)
+
+        self._region = region or (parts.hostname or None)
+        self._endpoint = endpoint or _q1(q, "endpoint")
+        self._queue_url_prefix = queue_url_prefix or _q1(q, "prefix")
+        self._wait_time = wait_time if wait_time is not None else _qint(q, "wait_time")
+        self._visibility_timeout = (
+            visibility_timeout if visibility_timeout is not None else _qint(q, "visibility_timeout")
+        )
+        self._fifo = fifo or _qbool(q, "fifo")
+        self._message_group_id = message_group_id or _q1(q, "group_id")
+        self._content_dedup = content_dedup or _qbool(q, "content_dedup")
+        self._urls: Dict[str, str] = {}
+
+        if client is not None:
+            self._sqs = client
+            return
+        try:
+            import boto3
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ImportError(
+                "SqsTransport requires the 'boto3' package. Install with "
+                'pip install "babelqueue[sqs]".'
+            ) from exc
+        kwargs: Dict[str, Any] = {}
+        if self._region:
+            kwargs["region_name"] = self._region
+        if self._endpoint:
+            kwargs["endpoint_url"] = self._endpoint
+        self._sqs = boto3.client("sqs", **kwargs)  # pragma: no cover - needs AWS/LocalStack
+
+    # -- helpers ------------------------------------------------------------
+
+    def _resolve_url(self, name: str) -> str:
+        cached = self._urls.get(name)
+        if cached is not None:
+            return cached
+        if self._queue_url_prefix:
+            url = self._queue_url_prefix.rstrip("/") + "/" + name
+        else:
+            url = self._sqs.get_queue_url(QueueName=name)["QueueUrl"]
+        self._urls[name] = url
+        return url
+
+    @staticmethod
+    def _attributes(body: str) -> Dict[str, Dict[str, str]]:
+        """Project the envelope's contract fields onto SQS MessageAttributes — a
+        redundant, routable view of the body (the body stays authoritative)."""
+        try:
+            env: Dict[str, Any] = EnvelopeCodec.decode(body)
+        except (ValueError, TypeError):  # pragma: no cover - decode is defensive
+            return {}
+        meta = env.get("meta") or {}
+
+        def s(v: Any) -> Dict[str, str]:
+            return {"DataType": "String", "StringValue": str(v)}
+
+        def n(v: Any) -> Dict[str, str]:
+            return {"DataType": "Number", "StringValue": str(v)}
+
+        attrs: Dict[str, Dict[str, str]] = {}
+        if env.get("job"):
+            attrs["bq-job"] = s(env["job"])
+        if env.get("trace_id"):
+            attrs["bq-trace-id"] = s(env["trace_id"])
+        if meta.get("id"):
+            attrs["bq-message-id"] = s(meta["id"])
+        if meta.get("schema_version") is not None:
+            attrs["bq-schema-version"] = n(meta["schema_version"])
+        if meta.get("lang"):
+            attrs["bq-source-lang"] = s(meta["lang"])
+        if meta.get("created_at") is not None:
+            attrs["bq-created-at"] = n(meta["created_at"])
+        return attrs
+
+    @staticmethod
+    def _reconcile(body: str, receive_count: Any) -> str:
+        """Set attempts to max(current, ApproximateReceiveCount - 1): a first delivery
+        reads 0, a natively-redelivered message reflects its true count, and a
+        runtime-incremented counter is never lowered."""
+        try:
+            rc = int(receive_count)
+        except (ValueError, TypeError):
+            return body
+        if rc <= 1:
+            return body
+        env = EnvelopeCodec.decode(body)
+        if not env:
+            return body
+        native = rc - 1
+        if native <= int(env.get("attempts", 0)):
+            return body
+        env["attempts"] = native
+        return EnvelopeCodec.encode(env)
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        params: Dict[str, Any] = {"QueueUrl": self._resolve_url(queue), "MessageBody": body}
+        attrs = self._attributes(body)
+        if attrs:
+            params["MessageAttributes"] = attrs
+        if self._fifo:
+            params["MessageGroupId"] = self._message_group_id or queue
+            if not self._content_dedup:
+                msg_id = (EnvelopeCodec.decode(body).get("meta") or {}).get("id")
+                if msg_id:
+                    params["MessageDeduplicationId"] = msg_id
+        self._sqs.send_message(**params)
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        wait = int(timeout) if timeout and timeout > 0 else 0
+        if wait > 20:
+            wait = 20
+        if self._wait_time is not None and self._wait_time < wait:
+            wait = self._wait_time
+        params: Dict[str, Any] = {
+            "QueueUrl": self._resolve_url(queue),
+            "MaxNumberOfMessages": 1,
+            "WaitTimeSeconds": wait,
+            "MessageAttributeNames": ["All"],
+            "AttributeNames": ["ApproximateReceiveCount"],
+        }
+        if self._visibility_timeout is not None:
+            params["VisibilityTimeout"] = self._visibility_timeout
+        resp = self._sqs.receive_message(**params)
+        messages = resp.get("Messages") or []
+        if not messages:
+            return None
+        msg = messages[0]
+        body = msg.get("Body", "")
+        receive_count = (msg.get("Attributes") or {}).get("ApproximateReceiveCount")
+        if receive_count is not None:
+            body = self._reconcile(body, receive_count)
+        return ReceivedMessage(body=body, queue=queue, handle=msg.get("ReceiptHandle"))
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if not message.handle:
+            return
+        self._sqs.delete_message(
+            QueueUrl=self._resolve_url(message.queue), ReceiptHandle=message.handle
+        )
+
+
+def _q1(q: Dict[str, list], key: str) -> Optional[str]:
+    values = q.get(key)
+    return values[0] if values else None
+
+
+def _qint(q: Dict[str, list], key: str) -> Optional[int]:
+    v = _q1(q, key)
+    if v is None:
+        return None
+    try:
+        return int(v)
+    except ValueError:  # pragma: no cover - defensive
+        return None
+
+
+def _qbool(q: Dict[str, list], key: str) -> bool:
+    v = _q1(q, key)
+    return v is not None and v.lower() in ("1", "true", "yes", "on")

{babelqueue-0.5.0 → babelqueue-1.1.0}/src/babelqueue/transport.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from collections import defaultdict, deque
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any, Deque, Dict, Optional
 
 from .exceptions import BabelQueueError
@@ -79,8 +79,12 @@ def make_transport(broker_url: str) -> Transport:
         from .pika_transport import PikaTransport
 
         return PikaTransport(broker_url)
+    if scheme == "sqs":
+        from .sqs_transport import SqsTransport
+
+        return SqsTransport(broker_url)
 
     raise BabelQueueError(
-        f"Unsupported broker scheme {scheme!r}. Use 'memory://', 'redis://' or "
-        "'amqp://', or pass your own Transport via BabelQueue(transport=...)."
+        f"Unsupported broker scheme {scheme!r}. Use 'memory://', 'redis://', "
+        "'amqp://' or 'sqs://', or pass your own Transport via BabelQueue(transport=...)."
     )

babelqueue-1.1.0/tests/conformance/manifest.json

@@ -0,0 +1,97 @@
+{
+  "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"
+    }
+  ],
+  "sqs": {
+    "description": "Amazon SQS binding conformance (broker-bindings.md §3). Every SDK that ships an SQS transport must satisfy these. The envelope body stays byte-identical (the 'cases' above); these lock the native projection + reconciliation the binding adds. Per-message values reuse fixtures/order-created.json so the expected attributes are deterministic.",
+    "attribute_projection": {
+      "description": "On produce, the transport MUST project these native MessageAttributes from the envelope (a redundant, routable view of the body; ids/strings are DataType String, counters are DataType Number). Applies to every SQS-producing SDK.",
+      "envelope_file": "fixtures/order-created.json",
+      "message_attributes": {
+        "bq-job":            { "DataType": "String", "StringValue": "urn:babel:orders:created" },
+        "bq-trace-id":       { "DataType": "String", "StringValue": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b" },
+        "bq-message-id":     { "DataType": "String", "StringValue": "f1e2d3c4-b5a6-4789-90ab-cdef01234567" },
+        "bq-schema-version": { "DataType": "Number", "StringValue": "1" },
+        "bq-source-lang":    { "DataType": "String", "StringValue": "php" },
+        "bq-created-at":     { "DataType": "Number", "StringValue": "1749132727000" }
+      }
+    },
+    "attempts_reconciliation": {
+      "description": "On consume, attempts = max(body.attempts, ApproximateReceiveCount - 1): a first delivery reads 0, an absent/garbage count is ignored, a runtime-incremented count is never lowered. Applies to SDKs that reconcile the envelope body on consume (the framework-less/runtime transports). A drop-in driver that surfaces the broker's native delivery count instead (e.g. Laravel's SqsJob.attempts() = ApproximateReceiveCount) is exempt — it documents that divergence.",
+      "cases": [
+        { "name": "first-delivery",        "body_attempts": 0, "approximate_receive_count": "1",            "expected_attempts": 0 },
+        { "name": "third-delivery",        "body_attempts": 0, "approximate_receive_count": "3",            "expected_attempts": 2 },
+        { "name": "native-exceeds-body",   "body_attempts": 2, "approximate_receive_count": "5",            "expected_attempts": 4 },
+        { "name": "never-lower-runtime",   "body_attempts": 5, "approximate_receive_count": "1",            "expected_attempts": 5 },
+        { "name": "garbage-count-ignored", "body_attempts": 4, "approximate_receive_count": "not-a-number", "expected_attempts": 4 },
+        { "name": "absent-count",          "body_attempts": 3, "approximate_receive_count": null,           "expected_attempts": 3 }
+      ]
+    }
+  }
+}