babelqueue 1.15.0__tar.gz → 1.16.0__tar.gz

{babelqueue-1.15.0 → babelqueue-1.16.0}/.github/workflows/ci.yml

@@ -17,10 +17,10 @@ jobs:
       matrix:
         python: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python }}
 
@@ -36,9 +36,9 @@ jobs:
     name: Static analysis (ruff + mypy)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install (dev + all adapters for type context)
@@ -79,10 +79,10 @@ jobs:
         ports:
           - 9324:9324
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -115,10 +115,10 @@ jobs:
     name: Conformance suite in sync
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Verify vendored conformance matches the canonical suite
         run: |
-          git clone --depth 1 --branch v1.0.0 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          git clone --depth 1 --branch v1.1.0 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
           diff -u "$RUNNER_TEMP/conformance/CONFORMANCE_VERSION" "tests/conformance/CONFORMANCE_VERSION"
           diff -ru "$RUNNER_TEMP/conformance/manifest.json" "tests/conformance/manifest.json"
           diff -ru "$RUNNER_TEMP/conformance/fixtures"      "tests/conformance/fixtures"

{babelqueue-1.15.0 → babelqueue-1.16.0}/.github/workflows/release.yml

@@ -18,10 +18,10 @@ jobs:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed
       contents: write   # create the GitHub release
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -41,6 +41,6 @@ jobs:
         #     password: ${{ secrets.PYPI_API_TOKEN }}
 
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true

{babelqueue-1.15.0 → babelqueue-1.16.0}/CHANGELOG.md

@@ -9,6 +9,40 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-10-10
+
+### Added
+- New optional `Rewinder` protocol (`rewind(message)`), implemented by `KafkaTransport` and
+  exported from `babelqueue` (public API, MINOR). The runtime calls it after a failed
+  version-gate dead-letter write and then pauses briefly (1 s) before the next poll.
+
+### Fixed
+- **`bq-schema-version` pre-decode gate on the SQS, Azure Service Bus, Kafka and Artemis
+  transports** (`pop`). The broker's schema-version property is read **before** the body is
+  decoded (broker-bindings §3.7 / §4.7 / §6.7 / §7.7), mirroring the existing Pulsar gate:
+  a missing or blank value (empty or only ASCII whitespace) takes the normal path; anything
+  else is compared untrimmed to `"1"` and a mismatch is returned with the raw body and the
+  reserved route `babelqueue:unsupported-schema-version:<v>` (version percent-escaped) without
+  decoding it. SQS/ASB/Kafka read `bq-schema-version`, Artemis `bq_schema_version`
+  (ADR-0017); ASB and Artemis also accept an integer `1` (a `bool` is not `1`). The conformance suite now reads each binding's
+  `schema_version_gate` table (including Pulsar's). No wire change.
+- **A version-gated delivery is dead-lettered directly, never retried.** `BabelQueue` now
+  sends a message under the reserved gate route straight to the DLQ (reason `unknown_urn`,
+  body untouched) when `dead_letter` is enabled and drops it otherwise, regardless of
+  `max_attempts` / `on_unknown_urn`. A retry would re-publish through paths that rebuild the
+  version header from the (valid) body (ASB/Kafka/Artemis) or never advance the attempt
+  counter (SQS), letting the gate be bypassed or the message loop. Applies to Pulsar too
+  (previously it retried up to `max_attempts` first).
+  If the dead-letter write itself fails, the message is still never retried: it is left
+  unacknowledged (an error is logged) so the broker redelivers it and the gate rejects it again
+  (SQS at the visibility timeout, Azure Service Bus at lock expiry, Artemis when the link or
+  connection closes). Kafka commits offsets cumulatively, so merely not acknowledging the
+  record would lose it once a later record is committed: `KafkaTransport` now `seek`s the
+  partition back to the failed record's offset so it is polled again and the dead-letter write
+  is retried (no commit moves past it).
+- The rejected `bq-schema-version` value is capped at 64 characters plus `...` in the log and
+  the route.
+
 ## [1.15.0] - 2026-10-10
 
 ### Added

{babelqueue-1.15.0 → babelqueue-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.15.0
+Version: 1.16.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
@@ -178,6 +178,43 @@ app.run()                               # consume forever (Ctrl-C to stop)
   the message unchanged once `shutdown_timeout` expires. Delivery is
   **at-least-once** — keep handlers idempotent (see the idempotency helper).
 
+### Unsupported `schema_version` (SQS, Azure Service Bus, Kafka, Artemis, Pulsar)
+
+These transports read the binding's schema-version property (`bq-schema-version`; Artemis
+`bq_schema_version`) **before** decoding the body. A missing or blank value (empty or only
+ASCII whitespace) follows the normal path; any other value must be exactly `"1"` (compared
+untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message carrying
+anything else is not decoded: it reaches the runtime on the reserved route
+`babelqueue:unsupported-schema-version:<v>` (the version percent-escaped) and is **never
+retried** — it goes straight to the dead-letter queue (reason `unknown_urn`, the body kept
+verbatim) when `dead_letter` is enabled, and is dropped otherwise, whatever `max_attempts` is.
+It does not depend on a broker `RedrivePolicy`. If the dead-letter write fails the message is
+left unacknowledged (an error is logged), is never retried and never reaches a handler; the
+dead-letter write is attempted again when the broker brings it back, which depends on the
+broker:
+
+- **SQS** — redelivered when the visibility timeout expires.
+- **Azure Service Bus** — redelivered when the message lock expires.
+- **Artemis** — an unsettled AMQP 1.0 delivery is returned only when the link or connection
+  closes, so it stays unsettled until then.
+- **Kafka** — offsets are committed cumulatively per partition, so merely skipping the commit
+  would lose the record once a later one is committed. The transport therefore implements
+  the optional `Rewinder` protocol: it `seek`s the partition back to the failed record's
+  offset and pauses `_rewind_pause` (1 s by default, so an unavailable DLQ is not hammered)
+  before the record is polled again; the gate rejects it again and the dead-letter write
+  is retried. While the dead-letter write keeps failing (for example the `.dlq` topic is not
+  writable) the partition **stalls on that record** (head-of-line blocking, consumer lag
+  grows) and the worker waits the pause on every attempt, which also delays its other
+  partitions and queues. The commit does not move past the record as long as the seek
+  succeeds; if the seek itself fails, an error naming the topic, partition and offset is
+  logged and a later commit on that partition may skip the record, so recover it by hand from
+  that offset. If the partition was lost to a rebalance, the new owner resumes from the last
+  committed offset and the record is not lost.
+- **Pulsar** — acknowledgement is per message; the unacknowledged message is redelivered by
+  the broker.
+
+A warning naming the version (cut at 64 characters plus `...`) and queue is logged.
+
 ### SQS release and poison messages
 
 On a handler failure, unknown-URN `release` or shutdown release, the SQS

{babelqueue-1.15.0 → babelqueue-1.16.0}/README.md

@@ -124,6 +124,43 @@ app.run()                               # consume forever (Ctrl-C to stop)
   the message unchanged once `shutdown_timeout` expires. Delivery is
   **at-least-once** — keep handlers idempotent (see the idempotency helper).
 
+### Unsupported `schema_version` (SQS, Azure Service Bus, Kafka, Artemis, Pulsar)
+
+These transports read the binding's schema-version property (`bq-schema-version`; Artemis
+`bq_schema_version`) **before** decoding the body. A missing or blank value (empty or only
+ASCII whitespace) follows the normal path; any other value must be exactly `"1"` (compared
+untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message carrying
+anything else is not decoded: it reaches the runtime on the reserved route
+`babelqueue:unsupported-schema-version:<v>` (the version percent-escaped) and is **never
+retried** — it goes straight to the dead-letter queue (reason `unknown_urn`, the body kept
+verbatim) when `dead_letter` is enabled, and is dropped otherwise, whatever `max_attempts` is.
+It does not depend on a broker `RedrivePolicy`. If the dead-letter write fails the message is
+left unacknowledged (an error is logged), is never retried and never reaches a handler; the
+dead-letter write is attempted again when the broker brings it back, which depends on the
+broker:
+
+- **SQS** — redelivered when the visibility timeout expires.
+- **Azure Service Bus** — redelivered when the message lock expires.
+- **Artemis** — an unsettled AMQP 1.0 delivery is returned only when the link or connection
+  closes, so it stays unsettled until then.
+- **Kafka** — offsets are committed cumulatively per partition, so merely skipping the commit
+  would lose the record once a later one is committed. The transport therefore implements
+  the optional `Rewinder` protocol: it `seek`s the partition back to the failed record's
+  offset and pauses `_rewind_pause` (1 s by default, so an unavailable DLQ is not hammered)
+  before the record is polled again; the gate rejects it again and the dead-letter write
+  is retried. While the dead-letter write keeps failing (for example the `.dlq` topic is not
+  writable) the partition **stalls on that record** (head-of-line blocking, consumer lag
+  grows) and the worker waits the pause on every attempt, which also delays its other
+  partitions and queues. The commit does not move past the record as long as the seek
+  succeeds; if the seek itself fails, an error naming the topic, partition and offset is
+  logged and a later commit on that partition may skip the record, so recover it by hand from
+  that offset. If the partition was lost to a rebalance, the new owner resumes from the last
+  committed offset and the record is not lost.
+- **Pulsar** — acknowledgement is per message; the unacknowledged message is redelivered by
+  the broker.
+
+A warning naming the version (cut at 64 characters plus `...`) and queue is logged.
+
 ### SQS release and poison messages
 
 On a handler failure, unknown-URN `release` or shutdown release, the SQS

{babelqueue-1.15.0 → babelqueue-1.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.15.0"
+version = "1.16.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"

{babelqueue-1.15.0 → babelqueue-1.16.0}/src/babelqueue/__init__.py

@@ -34,11 +34,12 @@ from .transport import (
     InMemoryTransport,
     ReceivedMessage,
     Redeliverer,
+    Rewinder,
     RoutedPublisher,
     Transport,
 )
 
-__version__ = "1.15.0"
+__version__ = "1.16.0"
 
 __all__ = [
     "BabelQueue",
@@ -53,6 +54,7 @@ __all__ = [
     "ReceivedMessage",
     "HeaderPublisher",
     "Redeliverer",
+    "Rewinder",
     "RoutedPublisher",
     "BabelQueueError",
     "UnknownUrnError",

{babelqueue-1.15.0 → babelqueue-1.16.0}/src/babelqueue/app.py

@@ -43,6 +43,7 @@ from .transport import (
     HeaderPublisher,
     ReceivedMessage,
     Redeliverer,
+    Rewinder,
     Transport,
     make_transport,
     publish_keeping_route,
@@ -111,6 +112,7 @@ class BabelQueue:
         self.shutdown_timeout = float(shutdown_timeout)
         self._handlers: Dict[str, Handler] = {}
         self._stop = threading.Event()
+        self._rewind_pause = 1.0  # seconds to wait before a rewound gated message is re-polled
         self._phase = _IDLE
         self._last_phase = _IDLE
         self._signalled = False
@@ -295,6 +297,20 @@ class BabelQueue:
                 self._phase = _SETTLING
             except Exception as exc:  # noqa: BLE001 - one bad message must not kill the loop
                 self._phase = _SETTLING
+                if received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+                    # A version-gated delivery never takes the generic retry path, even when its
+                    # dead-letter write fails: a retry re-publish may rebuild the version header
+                    # from the (valid) body and walk the message past the gate into a handler.
+                    # It is left unacked; the broker (or a rewind, for cumulative-offset brokers
+                    # such as Kafka) brings it back and the gate rejects it again.
+                    logger.error(
+                        "Dead-lettering a version-gated message on queue %r failed; it was NOT "
+                        "retried or acknowledged; it will come back and the dead-letter write will be retried.",
+                        received.queue,
+                        exc_info=exc,
+                    )
+                    self._rewind_unsettled(received)
+                    return
                 self._retry_or_dead_letter(received, envelope, exc)
             else:
                 # Outside the handler's try: a failed ack is not a handler failure, so it must
@@ -417,6 +433,23 @@ class BabelQueue:
                 exc_info=True,
             )
 
+    def _rewind_unsettled(self, received: ReceivedMessage) -> None:
+        """Make a deliberately unsettled message come back (cumulative-offset brokers such as Kafka
+        would otherwise lose it when a later record on the partition is committed), after a short
+        pause so an unavailable DLQ is not hammered in a hot loop."""
+        if not isinstance(self.transport, Rewinder):
+            return
+        try:
+            self.transport.rewind(received)
+        except Exception:  # noqa: BLE001 - reported, never kills the loop
+            logger.error(
+                "Failed to rewind an unsettled version-gated message on queue %r.",
+                received.queue,
+                exc_info=True,
+            )
+            return
+        self._stop.wait(self._rewind_pause)
+
     def _release_unprocessed(self, received: ReceivedMessage) -> None:
         """Release a message whose handler never completed (shutdown): unchanged body, no
         backoff, and the runtime adds no ``attempts`` increment. A broker that counts
@@ -440,23 +473,35 @@ class BabelQueue:
         if strategy == UnknownUrnStrategy.DELETE:
             self._ack_settled(received)
             return
-        # A transport's version-gated delivery, an undecodable body or a body naming no URN can
-        # never gain a handler, so releasing it unchanged would redeliver it forever. It takes the
-        # bounded FAIL path instead (retry up to max_attempts, then dead-letter or drop); only a
-        # genuinely unknown URN keeps the verbatim release.
-        gated = received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX)
-        poison = gated or not urn
-        if strategy == UnknownUrnStrategy.RELEASE and not poison:
+        # A transport's version-gated delivery (unsupported ``bq-schema-version``) can never gain
+        # a handler and must not be retried: a retry re-publishes through paths that may rebuild
+        # the version header from the (valid) body, or never advance the attempt counter, so the
+        # gate would be bypassed or the message would loop. It goes straight to the DLQ (or is
+        # dropped when no DLQ is configured).
+        if received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+            self._settle_version_gated(received, envelope)
+            return
+        # An undecodable body or a body naming no URN can never gain a handler either, so
+        # releasing it unchanged would redeliver it forever. It takes the bounded FAIL path
+        # instead (retry up to max_attempts, then dead-letter or drop); only a genuinely unknown
+        # URN keeps the verbatim release.
+        if strategy == UnknownUrnStrategy.RELEASE and urn:
             self._release(received, received.body, self.unknown_urn_release_delay)
             return
         if strategy == UnknownUrnStrategy.DEAD_LETTER:
             self._dead_letter(received, dict(envelope), "unknown_urn", None)
             return
         # FAIL (and RELEASE of a poison message) — surfaced through the retry/dead-letter path
-        # (never kills the loop). A gated delivery names its reserved route (the rejected version).
-        raise UnknownUrnError(
-            f"No handler mapped for URN [{urn or (received.route_urn if gated else '') or '(empty)'}]."
-        )
+        # (never kills the loop).
+        raise UnknownUrnError(f"No handler mapped for URN [{urn or '(empty)'}].")
+
+    def _settle_version_gated(self, received: ReceivedMessage, envelope: Mapping[str, Any]) -> None:
+        """Dead-letter a version-gated delivery directly (no retry); drop it when no DLQ is set."""
+        if self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
+            error = UnknownUrnError(f"No handler mapped for URN [{received.route_urn}].")
+            self._dead_letter(received, dict(envelope), "unknown_urn", error)
+            return
+        self._ack_settled(received)
 
     def _retry_or_dead_letter(
         self, received: ReceivedMessage, envelope: Dict[str, Any], exc: BaseException
@@ -500,7 +545,8 @@ class BabelQueue:
 #: Reserved ``ReceivedMessage.route_urn`` prefix a transport uses to hand over a delivery it
 #: version-gated (broker-bindings §5.7 step 3, e.g. the pulsar transport's ``bq-schema-version``
 #: check). Not a ``urn:babel:`` URN, so no handler owns it. Must equal
-#: ``pulsar_transport.UNSUPPORTED_SCHEMA_ROUTE_PREFIX`` (locked by a test); never reaches the wire.
+#: ``UNSUPPORTED_SCHEMA_ROUTE_PREFIX`` of the pulsar, sqs, asb, kafka and artemis transports (locked
+#: by a test); never reaches the wire. A delivery under it is dead-lettered directly, never retried.
 _UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 

{babelqueue-1.15.0 → babelqueue-1.16.0}/src/babelqueue/artemis_transport.py

@@ -32,10 +32,24 @@ transport directly and pass it via ``BabelQueue(transport=...)`` or
 
 from __future__ import annotations
 
+import logging
+import re
 from typing import Any, Dict, Optional
+from urllib.parse import quote
 
-from .codec import EnvelopeCodec, parse_envelope
-from .transport import ReceivedMessage, Transport
+from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .transport import ReceivedMessage, Transport, truncate_declared_version
+
+_logger = logging.getLogger("babelqueue.artemis")
+
+#: A blank ``bq_schema_version``: empty or only ASCII whitespace (space, \t, \n, \v, \f, \r) — the
+#: same set in every SDK (GR-5). Deliberately not ``str.strip()``, which also strips U+001C-U+001F,
+#: U+0085, U+00A0, U+2028, U+3000 ...
+_BLANK_ASCII_PATTERN = re.compile(r"[ \t\n\x0b\x0c\r]*")
+#: Prefix of the reserved ``route_urn`` a version-gated message is delivered under. It is not a
+#: ``urn:babel:`` URN, so no handler can legitimately own it; the runtime reports it as an
+#: unknown URN, which names the rejected ``bq_schema_version``.
+UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 JMS_TYPE_ANNOTATION = "x-opt-jms-type"
 APP_ID = "babelqueue"
@@ -187,6 +201,33 @@ class ArtemisTransport(Transport):
         except (TypeError, ValueError):  # pragma: no cover - defensive
             return 0
 
+    @staticmethod
+    def _unsupported_schema_version(properties: Any) -> Optional[str]:
+        """The §7.7 step-3 gate on the ``bq_schema_version`` application property (underscores —
+        ADR-0017): the offending raw value, or ``None``.
+
+        A missing property, a null value or a blank value (the empty string or only ASCII
+        whitespace — the same set in every SDK, GR-5, not ``str.strip()``) is not gated: the usual
+        decode path runs. A ``bytes`` value is decoded as UTF-8. A present value is accepted only
+        when it is exactly the core's supported ``SCHEMA_VERSION``: the string ``"1"`` or the
+        integer ``1`` (a ``bool`` is not an integer here, though it is one in Python); ``"2"``,
+        ``"x"``, ``"01"``, ``" 1"``, ``0``, ``2``, ``1.5``, ``True`` and any other type are
+        rejected."""
+        if not isinstance(properties, dict):
+            return None
+        raw = properties.get("bq_schema_version")
+        if raw is None:
+            return None
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", "replace")
+        if isinstance(raw, str):
+            if _BLANK_ASCII_PATTERN.fullmatch(raw) is not None or raw == str(SCHEMA_VERSION):
+                return None
+            return raw
+        if isinstance(raw, int) and not isinstance(raw, bool) and raw == SCHEMA_VERSION:
+            return None
+        return str(raw)
+
     @staticmethod
     def _payload(message: Any) -> str:
         body = getattr(message, "body", None)
@@ -212,6 +253,26 @@ class ArtemisTransport(Transport):
             raise
         if message is None:  # pragma: no cover - defensive (real client raises instead)
             return None
+        # §7.7 step 3: gate on the ``bq_schema_version`` property BEFORE any body decode (the
+        # attempts reconcile below decodes the body). A rejected message keeps its raw body and the
+        # reserved route; the runtime then dead-letters it directly (no retry).
+        unsupported = truncate_declared_version(
+            self._unsupported_schema_version(getattr(message, "properties", None))
+        )
+        if unsupported is not None:
+            _logger.warning(
+                "Artemis message on %r carries unsupported bq_schema_version %r (supported: %s); "
+                "not decoding it.",
+                queue,
+                unsupported,
+                SCHEMA_VERSION,
+            )
+            return ReceivedMessage(
+                body=self._payload(message),
+                queue=queue,
+                handle=receiver,
+                route_urn=UNSUPPORTED_SCHEMA_ROUTE_PREFIX + quote(unsupported, safe=""),
+            )
         body = self._reconcile(self._payload(message), self._delivery_count(message))
         return ReceivedMessage(body=body, queue=queue, handle=receiver)
 

{babelqueue-1.15.0 → babelqueue-1.16.0}/src/babelqueue/asb_transport.py

@@ -23,11 +23,24 @@ transport directly and pass it via ``BabelQueue(transport=...)`` or
 
 from __future__ import annotations
 
+import logging
+import re
 from typing import Any, Dict, Optional
-from urllib.parse import urlsplit
+from urllib.parse import quote, urlsplit
 
-from .codec import EnvelopeCodec, parse_envelope
-from .transport import ReceivedMessage, Transport
+from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .transport import ReceivedMessage, Transport, truncate_declared_version
+
+_logger = logging.getLogger("babelqueue.asb")
+
+#: A blank ``bq-schema-version``: empty or only ASCII whitespace (space, \t, \n, \v, \f, \r) — the
+#: same set in every SDK (GR-5). Deliberately not ``str.strip()``, which also strips U+001C-U+001F,
+#: U+0085, U+00A0, U+2028, U+3000 ...
+_BLANK_ASCII_PATTERN = re.compile(r"[ \t\n\x0b\x0c\r]*")
+#: Prefix of the reserved ``route_urn`` a version-gated message is delivered under. It is not a
+#: ``urn:babel:`` URN, so no handler can legitimately own it; the runtime reports it as an
+#: unknown URN, which names the rejected ``bq-schema-version``.
+UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 
 class AsbTransport(Transport):
@@ -141,6 +154,42 @@ class AsbTransport(Transport):
         env["attempts"] = native
         return EnvelopeCodec.encode(env)
 
+    @staticmethod
+    def _unsupported_schema_version(properties: Any) -> Optional[str]:
+        """The §4.7 step-3 gate on the ``bq-schema-version`` application property: the offending
+        raw value as text, or ``None``.
+
+        The AMQP client may hand keys and values over as ``bytes``; both are decoded as UTF-8. A
+        missing property, or a blank string (the empty string or only ASCII whitespace — the same
+        set in every SDK, GR-5, not ``str.strip()``) is not gated: the usual decode path runs. A
+        present value is accepted only when it is exactly the core's supported ``SCHEMA_VERSION``:
+        the string ``"1"`` or the integer ``1`` (a ``bool`` is not an integer here, though it is
+        one in Python). ``"2"``, ``"x"``, ``"01"``, ``" 1"``, ``0``, ``2``, ``1.5``, ``True`` and
+        any other type are rejected."""
+        if not properties:
+            return None
+        raw: Any = None
+        try:
+            items = list(properties.items())
+        except (AttributeError, TypeError):
+            return None
+        for key, value in items:
+            name = key.decode("utf-8", "replace") if isinstance(key, (bytes, bytearray)) else key
+            if name == "bq-schema-version":
+                raw = value
+                break
+        if raw is None:
+            return None
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", "replace")
+        if isinstance(raw, str):
+            if _BLANK_ASCII_PATTERN.fullmatch(raw) is not None or raw == str(SCHEMA_VERSION):
+                return None
+            return raw
+        if isinstance(raw, int) and not isinstance(raw, bool) and raw == SCHEMA_VERSION:
+            return None
+        return str(raw)
+
     # -- Transport ----------------------------------------------------------
 
     def publish(self, queue: str, body: str) -> None:
@@ -157,6 +206,27 @@ class AsbTransport(Transport):
         if not messages:
             return None
         message = messages[0]
+        # §4.7 step 3: gate on ``bq-schema-version`` BEFORE any body decode (the attempts reconcile
+        # below decodes the body). A rejected message keeps its raw body and the reserved route.
+        unsupported = truncate_declared_version(
+            self._unsupported_schema_version(
+            getattr(message, "application_properties", None)
+        )
+        )
+        if unsupported is not None:
+            _logger.warning(
+                "Azure Service Bus message on %r carries unsupported bq-schema-version %r "
+                "(supported: %s); not decoding it.",
+                queue,
+                unsupported,
+                SCHEMA_VERSION,
+            )
+            return ReceivedMessage(
+                body=str(message),
+                queue=queue,
+                handle=message,
+                route_urn=UNSUPPORTED_SCHEMA_ROUTE_PREFIX + quote(unsupported, safe=""),
+            )
         body = self._reconcile(str(message), getattr(message, "delivery_count", None))
         return ReceivedMessage(body=body, queue=queue, handle=message)