babelqueue 1.23.0__tar.gz → 1.24.0__tar.gz

{babelqueue-1.23.0 → babelqueue-1.24.0}/.github/workflows/ci.yml

@@ -177,7 +177,7 @@ jobs:
           --health-retries 10
     env:
       # The pinned conformance release (ADR-0032). Bump together with tests/conformance/.
-      BQ_CONFORMANCE_VERSION: 1.7.0
+      BQ_CONFORMANCE_VERSION: 1.8.0
       # sha256 of that release's fetch.sh: the script runs on the runner, so it is pinned rather
       # than trusted from a mutable tag. Bump together with BQ_CONFORMANCE_VERSION.
       BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849

{babelqueue-1.23.0 → babelqueue-1.24.0}/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
     # Recommended for PyPI Trusted Publishing — configure a "pypi" environment +
     # a trusted publisher on PyPI (repo BabelQueue/babelqueue-python, this workflow).
     environment: pypi
-    # redis_layout (conformance 1.7.0) drives the real Lua scripts: a real redis:7 is mandatory,
+    # redis_layout (conformance 1.7.0+) drives the real Lua scripts: a real redis:7 is mandatory,
     # exactly as in ci.yml's `conformance` job — without it the cases are reported as failures.
     services:
       redis:
@@ -28,7 +28,7 @@ jobs:
           --health-retries 10
     env:
       # The pinned conformance release (ADR-0032). Keep identical to ci.yml.
-      BQ_CONFORMANCE_VERSION: 1.7.0
+      BQ_CONFORMANCE_VERSION: 1.8.0
       BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849
     permissions:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed

{babelqueue-1.23.0 → babelqueue-1.24.0}/CHANGELOG.md

@@ -9,6 +9,71 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-10-26
+
+Implements conformance **1.8.0** (vendored from the `v1.8.0` release asset, verified with
+`fetch.sh --check`; `BQ_CONFORMANCE_VERSION` is now `1.8.0` in `ci.yml` and `release.yml`). The
+envelope stays at `schema_version: 1`; nothing here touches the wire (ADR-0037). The new
+`version_gate_pulsar`, `version_gate_artemis`, `version_gate_sqs` and `version_gate_asb` sections run
+and pass (17 cases each; Python has the `on_unknown_urn` option, so no row is skipped). A MINOR.
+
+### Changed (behaviour)
+- **With the DLQ off, SQS and Azure Service Bus no longer drop a version-gated message or retry a
+  poison body; they are left to the broker's native mechanism (ADR-0037 decision 1 rule 3 and
+  decision 2 "Go and Python"; broker-bindings 3.5, 4.5, 5.7; owner decision 2026-10-25).**
+  - *Version-gated message* (an unsupported `bq-schema-version`), `dead_letter` off and a strategy
+    other than `DELETE` or `DEAD_LETTER`: it used to be acknowledged and dropped. It is now **not**
+    acknowledged. SQS: no `DeleteMessage`; visibility expiry redelivers it (the gate rejects it
+    again) and the queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`. Azure
+    Service Bus: an explicit native `DeadLetter` (reason `unsupported schema version`) into
+    `$DeadLetterQueue` instead of `Complete`.
+  - *Poison body* (invalid JSON or an identity-less object), `dead_letter` off and a strategy other
+    than `DELETE` or `DEAD_LETTER`: it used to take the bounded `FAIL` path (re-publish an empty
+    envelope up to `max_attempts`, then drop). On SQS and Azure Service Bus it is now settled
+    natively **on the first delivery** exactly as above (Azure Service Bus reason `poison`): no
+    re-publish, no retry, no ack, body unchanged, the event is logged. Every other transport
+    (Pulsar, Artemis, AMQP, Kafka, Redis, memory) keeps its behaviour; `DELETE` (ack and drop),
+    `dead_letter=True` and the `DEAD_LETTER` strategy (the raw record, then ack) are unchanged on
+    SQS and Azure Service Bus too.
+  - A deployment that relied on SQS/Azure Service Bus silently dropping these messages now needs a
+    `RedrivePolicy` (SQS) or accepts them in `$DeadLetterQueue` (Azure Service Bus), or sets
+    `dead_letter=True` / `on_unknown_urn=DELETE`.
+
+### Fixed
+- **SQS: the default dead-letter queue name is now `<queue>-dlq` (FIFO `<queue>-dlq.fifo`) (ADR-0037
+  decision 7).** The old default `<queue>.dlq` was never a valid Amazon SQS queue name (a name may hold only
+  alphanumerics, hyphens and underscores, plus one `.fifo` suffix), so a DLQ write by default could not find a
+  queue on real SQS. `dead_letter_suffix` now defaults to `None` ("not set"); unless `dead_letter_queue` is set
+  the runtime asks the transport's new optional `DeadLetterNamer` capability
+  (`dead_letter_queue_name(queue, suffix)`, exported from `babelqueue`), which `SqsTransport` implements. The
+  runtime also hands it an explicit `dead_letter_suffix`; on a FIFO queue the `.fifo` suffix always stays last,
+  an explicit suffix included: `orders.fifo` with `dead_letter_suffix="-x"` is `orders-x.fifo`, never
+  `orders.fifo-x` (an SQS FIFO name must end in `.fifo`; before, that explicit suffix produced the uncreatable
+  `orders.fifo-x`). An explicit queue name behaves as before; every other transport keeps `<queue>.dlq` (the
+  attribute `App.dead_letter_suffix` is `None` instead of `".dlq"` until set). Deployments
+  that relied on the SQS default must name the DLQ `<queue>-dlq`, or pass `dead_letter_suffix=".dlq"` /
+  `dead_letter_queue=` to keep the old name. An explicitly empty `dead_letter_suffix=""` now counts as "no suffix" on SQS (`-dlq`); before, it made the DLQ the source queue itself.
+
+### Added
+- **`babelqueue.transport.NativeSettler`**, an optional `Transport` capability
+  (`settle_native(message, reason, description)`). With the DLQ off the runtime calls it instead of
+  acknowledging a version-gated message (and, on the poison route, instead of the bounded retry) on
+  a transport that offers it; the decision follows the capability, never the transport's name.
+  `SqsTransport.settle_native` is a deliberate no-op on the wire; `AsbTransport.settle_native`
+  dead-letters natively (falling back to `abandon_message` for a receiver without
+  `dead_letter_message`). Transports without it are unchanged.
+- **`babelqueue.transport.Abandoner` and `AsbTransport.abandon`.** When the dead-letter write of a
+  *version-gated* message fails, Azure Service Bus now `Abandon`s the peek-lock (broker-bindings 4.5,
+  "A failed write `Abandon`s it") so the broker redelivers it at once, instead of leaving it locked until
+  the lock lapses (up to 5 minutes). Only that branch abandons (owner decision 2026-10-25): `AsbTransport`
+  is deliberately **not** a `Rewinder`, so a graceful-shutdown release and a failed retry re-publish keep
+  their previous handling (a copy is re-published and the original completed), and a failed dead-letter
+  write of a poison body is still left to its lock. Tests pin all three. The `version_gate_asb` runner
+  asserts the `Abandon` on its `unsettled` rows.
+- Conformance `version_gate_*` runners (`version_gate_pulsar` / `version_gate_artemis` through the
+  runtime, `version_gate_sqs` / `version_gate_asb` through the real transports) and their entries in
+  the results writer.
+
 ## [1.23.0] - 2026-10-25
 
 Implements ADR-0036 (post-R1 parity) decisions 2, 4, 5 and 6. A MINOR: every change is a

{babelqueue-1.23.0 → babelqueue-1.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.23.0
+Version: 1.24.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
@@ -212,8 +212,13 @@ untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message
 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 (the incoming body, byte-identical,
-with no `dead_letter` block) 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
+with no `dead_letter` block) when `dead_letter` is enabled (or `on_unknown_urn=DEAD_LETTER`), and
+`on_unknown_urn=DELETE` drops it, whatever `max_attempts` is. With `dead_letter` off, **SQS and Azure
+Service Bus no longer drop it** (ADR-0037): it is left to the broker's native mechanism and logged
+(SQS: no `DeleteMessage`, so visibility expiry redelivers it — the gate rejects it again — and the
+queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`; Azure Service Bus: an
+explicit native `DeadLetter` with reason `unsupported schema version` into `$DeadLetterQueue`
+instead of `Complete`). Kafka, Artemis and Pulsar still acknowledge and drop it. 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:
@@ -253,10 +258,17 @@ a warning. A **per-message delay** at publish time is
 standard queue; a larger value, or any per-message delay on a FIFO queue, raises
 `BabelQueueError` instead of being truncated or dropped).
 
+**Poison bodies.** A body that does not decode, or has no identity, is never retried by the SDK
+(ADR-0037): `dead_letter=True` writes the ADR-0035 record to the DLQ (`<queue>-dlq` on SQS, `<queue>.dlq` elsewhere) and then deletes it,
+`on_unknown_urn=DELETE` deletes it, and with the DLQ off it is **not deleted and not re-sent**: the
+transport's `settle_native` capability leaves it to SQS on the first delivery (visibility expiry,
+then the queue's `RedrivePolicy`; the event is logged). Azure Service Bus does the same with a native
+`DeadLetter` (reason `poison`). Every other transport keeps the bounded retry up to `max_attempts`.
+
 **Poison-loop risk:** a message that always fails is redelivered at once until
 `max_attempts` is reached. If the receive count is unavailable the SDK cannot
 advance attempts at all. **Configure a native `RedrivePolicy`**
-(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>.dlq`) on every SQS
+(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>-dlq`, the SQS default DLQ name: FIFO `<queue>-dlq.fifo`, because an SQS queue name cannot contain a dot; `dead_letter_queue` overrides it, and `dead_letter_suffix` replaces `-dlq`, placed before `.fifo` on a FIFO queue) on every SQS
 queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
 handler's dependencies need time to recover.
 

{babelqueue-1.23.0 → babelqueue-1.24.0}/README.md

@@ -158,8 +158,13 @@ untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message
 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 (the incoming body, byte-identical,
-with no `dead_letter` block) 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
+with no `dead_letter` block) when `dead_letter` is enabled (or `on_unknown_urn=DEAD_LETTER`), and
+`on_unknown_urn=DELETE` drops it, whatever `max_attempts` is. With `dead_letter` off, **SQS and Azure
+Service Bus no longer drop it** (ADR-0037): it is left to the broker's native mechanism and logged
+(SQS: no `DeleteMessage`, so visibility expiry redelivers it — the gate rejects it again — and the
+queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`; Azure Service Bus: an
+explicit native `DeadLetter` with reason `unsupported schema version` into `$DeadLetterQueue`
+instead of `Complete`). Kafka, Artemis and Pulsar still acknowledge and drop it. 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:
@@ -199,10 +204,17 @@ a warning. A **per-message delay** at publish time is
 standard queue; a larger value, or any per-message delay on a FIFO queue, raises
 `BabelQueueError` instead of being truncated or dropped).
 
+**Poison bodies.** A body that does not decode, or has no identity, is never retried by the SDK
+(ADR-0037): `dead_letter=True` writes the ADR-0035 record to the DLQ (`<queue>-dlq` on SQS, `<queue>.dlq` elsewhere) and then deletes it,
+`on_unknown_urn=DELETE` deletes it, and with the DLQ off it is **not deleted and not re-sent**: the
+transport's `settle_native` capability leaves it to SQS on the first delivery (visibility expiry,
+then the queue's `RedrivePolicy`; the event is logged). Azure Service Bus does the same with a native
+`DeadLetter` (reason `poison`). Every other transport keeps the bounded retry up to `max_attempts`.
+
 **Poison-loop risk:** a message that always fails is redelivered at once until
 `max_attempts` is reached. If the receive count is unavailable the SDK cannot
 advance attempts at all. **Configure a native `RedrivePolicy`**
-(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>.dlq`) on every SQS
+(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>-dlq`, the SQS default DLQ name: FIFO `<queue>-dlq.fifo`, because an SQS queue name cannot contain a dot; `dead_letter_queue` overrides it, and `dead_letter_suffix` replaces `-dlq`, placed before `.fifo` on a FIFO queue) on every SQS
 queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
 handler's dependencies need time to recover.
 

{babelqueue-1.23.0 → babelqueue-1.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.23.0"
+version = "1.24.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.23.0 → babelqueue-1.24.0}/src/babelqueue/__init__.py

@@ -30,10 +30,13 @@ from .exceptions import BabelQueueError, DecryptError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
 from .transport import (
+    Abandoner,
     BatchPopper,
+    DeadLetterNamer,
     DeadLetterWriter,
     HeaderPublisher,
     InMemoryTransport,
+    NativeSettler,
     ReceivedMessage,
     Redeliverer,
     Rewinder,
@@ -42,7 +45,7 @@ from .transport import (
     Transport,
 )
 
-__version__ = "1.23.0"
+__version__ = "1.24.0"
 
 __all__ = [
     "BabelQueue",
@@ -55,9 +58,12 @@ __all__ = [
     "Transport",
     "InMemoryTransport",
     "ReceivedMessage",
+    "Abandoner",
     "BatchPopper",
+    "DeadLetterNamer",
     "DeadLetterWriter",
     "HeaderPublisher",
+    "NativeSettler",
     "Redeliverer",
     "Rewinder",
     "RoutedPublisher",

{babelqueue-1.23.0 → babelqueue-1.24.0}/src/babelqueue/app.py

@@ -43,8 +43,11 @@ from .replay import HEADER_REPLAY_BYPASS, _replay_scope
 from .routing import UnknownUrnStrategy
 from .transport import (
     NON_NUMERIC_ATTEMPTS_ROUTE,
+    Abandoner,
+    DeadLetterNamer,
     DeadLetterWriter,
     HeaderPublisher,
+    NativeSettler,
     PoisonRoute,
     ReceivedMessage,
     Redeliverer,
@@ -109,7 +112,7 @@ class BabelQueue:
         max_attempts: int = 3,
         dead_letter: bool = False,
         dead_letter_queue: Optional[str] = None,
-        dead_letter_suffix: str = ".dlq",
+        dead_letter_suffix: Optional[str] = None,
         retry_backoff: float = 0.0,
         retry_backoff_multiplier: float = 1.0,
         retry_backoff_max: float = 0.0,
@@ -143,6 +146,8 @@ class BabelQueue:
         self.max_attempts = max_attempts
         self.dead_letter_enabled = bool(dead_letter)
         self.dead_letter_queue = dead_letter_queue
+        #: ``None`` = not set: the transport's :class:`~babelqueue.transport.DeadLetterNamer` default
+        #: (SQS: ``<queue>-dlq``) or else ``.dlq``. An explicit value is handed to the namer.
         self.dead_letter_suffix = dead_letter_suffix
         self.retry_backoff = float(retry_backoff)
         if retry_jitter not in RETRY_JITTERS:
@@ -383,7 +388,10 @@ class BabelQueue:
                         received.queue,
                         exc_info=exc,
                     )
-                    self._rewind_unsettled(received)
+                    if received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+                        self._abandon_unsettled(received)
+                    else:
+                        self._rewind_unsettled(received)
                     return
                 self._retry_or_dead_letter(received, envelope, exc)
             else:
@@ -528,6 +536,49 @@ class BabelQueue:
                 exc_info=True,
             )
 
+    def _settle_native(self, received: ReceivedMessage, reason: str, description: str) -> bool:
+        """Hand ``received`` to the transport's :class:`~babelqueue.transport.NativeSettler`
+        capability and report whether it did: ``False`` means the transport has none and the caller
+        keeps its previous settle. The event is logged and never retried by the SDK; a failing call
+        is logged too and leaves the message unacknowledged (the broker redelivers it)."""
+        if not isinstance(self.transport, NativeSettler):
+            return False
+        logger.warning(
+            "Left to the broker's native mechanism (not acknowledged, not retried): queue %r, "
+            "route %r, reason %s.",
+            received.queue, received.route_urn, reason,
+        )
+        try:
+            self.transport.settle_native(received, reason, description)
+        except Exception:  # noqa: BLE001 - reported, never kills the loop
+            logger.error(
+                "Native settle of a message on queue %r failed; it stays unacknowledged and will "
+                "be redelivered by the broker.",
+                received.queue,
+                exc_info=True,
+            )
+        return True
+
+    def _abandon_unsettled(self, received: ReceivedMessage) -> None:
+        """A version-gated delivery whose dead-letter write failed: a :class:`Rewinder` transport is
+        rewound (:meth:`_rewind_unsettled`); an :class:`~babelqueue.transport.Abandoner` transport
+        (Azure Service Bus) abandons its lock so the broker redelivers it at once, after the same
+        short pause. Any other transport leaves it to its lock or visibility timeout."""
+        if isinstance(self.transport, Rewinder) or not isinstance(self.transport, Abandoner):
+            self._rewind_unsettled(received)
+            return
+        try:
+            self.transport.abandon(received)
+        except Exception:  # noqa: BLE001 - reported, never kills the loop
+            logger.error(
+                "Failed to abandon an unsettled version-gated message (route %r) on queue %r.",
+                received.route_urn,
+                received.queue,
+                exc_info=True,
+            )
+            return
+        self._stop.wait(self._rewind_pause)
+
     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
@@ -717,10 +768,15 @@ class BabelQueue:
         * with the DLQ on (``dead_letter`` or the DEAD_LETTER strategy) it is written to the DLQ as
           the ADR-0035 record with ``reason: "poison"`` (original body preserved) and acknowledged
           after the write, with no retry;
-        * with the DLQ off it takes the bounded FAIL path (``RELEASE`` is replaced by it, a poison
-          body would otherwise be released forever): re-published with ``attempts + 1`` up to
-          ``max_attempts``, then dropped. The count is the larger of the transport's own delivery
-          count and the ``attempts`` of the bare body a previous retry left behind.
+        * with the DLQ off, on a transport with a native mechanism (SQS, Azure Service Bus: the
+          :class:`~babelqueue.transport.NativeSettler` capability) it is settled natively on the first
+          delivery -- not acknowledged, not re-published, not retried, body unchanged (ADR-0037
+          decision 2);
+        * with the DLQ off on any other transport it takes the bounded FAIL path (``RELEASE`` is
+          replaced by it, a poison body would otherwise be released forever): re-published with
+          ``attempts + 1`` up to ``max_attempts``, then dropped. The count is the larger of the
+          transport's own delivery count and the ``attempts`` of the bare body a previous retry left
+          behind.
 
         A failed DLQ write propagates: :meth:`dispatch` leaves the delivery unacknowledged."""
         if self.on_unknown_urn == UnknownUrnStrategy.DELETE:
@@ -734,6 +790,11 @@ class BabelQueue:
         if self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
             self._settle_transport_poison(received, cause, attempts)
             return
+        # DLQ off, strategy neither delete nor a writable dead_letter: a transport with a native
+        # mechanism (SQS, Azure Service Bus) settles the poison body natively on the first delivery
+        # (ADR-0037 decision 2, "Go and Python") instead of the bounded retry below.
+        if self._settle_native(received, "poison", "the body does not decode into a valid envelope: " + cause):
+            return
         self._retry_or_dead_letter(
             received,
             {"attempts": attempts},
@@ -779,11 +840,20 @@ class BabelQueue:
         )
 
     def _dead_letter_target(self, received: ReceivedMessage) -> str:
-        """The queue a dead-lettered delivery is written to (configured DLQ or ``<queue><suffix>``)."""
-        return self.dead_letter_queue or (received.queue + self.dead_letter_suffix)
+        """The queue a dead-lettered delivery is written to: the configured ``dead_letter_queue``, else
+        the transport's :class:`~babelqueue.transport.DeadLetterNamer` name (SQS: ``<queue>-dlq``, FIFO
+        ``<queue>-dlq.fifo``, an explicit ``dead_letter_suffix`` placed before ``.fifo``; ADR-0037
+        decision 7), else ``<queue><dead_letter_suffix>`` (default ``.dlq``)."""
+        if self.dead_letter_queue:
+            return self.dead_letter_queue
+        if isinstance(self.transport, DeadLetterNamer):
+            return self.transport.dead_letter_queue_name(received.queue, self.dead_letter_suffix)
+        return received.queue + (".dlq" if self.dead_letter_suffix is None else self.dead_letter_suffix)
 
     def _settle_version_gated(self, received: ReceivedMessage, always: bool = False) -> None:
-        """Dead-letter a version-gated delivery directly (no retry); drop it when no DLQ is set.
+        """Dead-letter a version-gated delivery directly (no retry). With no DLQ set it is left to the
+        transport's native mechanism when the transport has the :class:`~babelqueue.transport.NativeSettler`
+        capability (SQS, Azure Service Bus; ADR-0037 decision 1 rule 3) and dropped otherwise.
 
         ``always`` writes the DLQ record in every configuration, ignoring ``dead_letter_enabled``.
         A Kafka poison record reaches it with the DLQ already on (:meth:`_route_poison`). The Redis
@@ -798,7 +868,15 @@ class BabelQueue:
         if always or self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
             self._write_dead_letter(received, self._dead_letter_target(received), received.body)
             return
-        # No DLQ to hold it: the drop is deliberate, but it must not be silent.
+        # No DLQ to hold it (broker-bindings §5.7 rule 3). A transport with a native mechanism (SQS,
+        # Azure Service Bus) leaves it to that mechanism instead of dropping it (ADR-0037 decision 1).
+        if self._settle_native(
+            received,
+            "unsupported schema version",
+            "the message declares a schema version this consumer does not support",
+        ):
+            return
+        # Any other transport: the drop is deliberate, but it must not be silent.
         logger.warning(
             "Dropping an undeliverable message on queue %r (route %r, %d body characters): it can "
             "never be handled and no dead-letter queue is configured.",

{babelqueue-1.23.0 → babelqueue-1.24.0}/src/babelqueue/asb_transport.py

@@ -12,6 +12,10 @@ Consuming uses the PeekLock reservation model (``receive_messages`` -> process -
 ``DeliveryCount`` (1-based), reconciled onto the envelope as ``attempts = DeliveryCount - 1``.
 A message left un-acked has its lock expire and is redelivered (at-least-once).
 
+A version-gated message (``bq-schema-version`` the consumer does not support) or a poison body is, with
+dead-lettering off, not completed: :meth:`AsbTransport.settle_native` dead-letters it natively into
+``$DeadLetterQueue`` (ADR-0037).
+
 This implements §4 of the broker-bindings contract. The envelope is unchanged
 (``schema_version`` stays 1); Azure Service Bus is purely additive.
 
@@ -269,6 +273,39 @@ class AsbTransport(Transport):
             return
         self._receiver(message.queue).complete_message(message.handle)
 
+    def abandon(self, message: ReceivedMessage) -> None:
+        """:class:`~babelqueue.transport.Abandoner`: abandon the peek-lock on ``message`` so the
+        broker redelivers it right away (``AbandonMessage``) instead of when the lock lapses.
+        Nothing is completed or dead-lettered and the body is untouched. The runtime calls it only
+        when the dead-letter write of a version-gated message failed (broker-bindings 4.5, "A failed
+        write ``Abandon``s it"). This transport is deliberately **not** a
+        :class:`~babelqueue.transport.Rewinder`, so a graceful-shutdown release and a failed retry
+        re-publish keep their previous handling (copy re-publish and ``Complete``). A message
+        without a handle, or a receiver without ``abandon_message`` (a test fake), leaves the lock to
+        lapse."""
+        if message.handle is None:
+            return
+        abandon = getattr(self._receiver(message.queue), "abandon_message", None)
+        if abandon is not None:
+            abandon(message.handle)
+
+    def settle_native(self, message: ReceivedMessage, reason: str, description: str) -> None:
+        """Dead-letter ``message`` natively (:class:`~babelqueue.transport.NativeSettler`, ADR-0037
+        decisions 1 and 2): a version-gated delivery or a poison body that the runtime may neither
+        process nor drop, with dead-lettering off, is moved by an explicit ``DeadLetter`` (reason
+        ``"unsupported schema version"`` or ``"poison"``, plus the description) into the entity's
+        ``$DeadLetterQueue``. Nothing is completed, re-published or retried, and the body is
+        unchanged. A receiver without ``dead_letter_message`` abandons the lock instead (also a
+        conformant native settle: ``MaxDeliveryCount`` takes over)."""
+        if message.handle is None:
+            return
+        receiver = self._receiver(message.queue)
+        dead_letter = getattr(receiver, "dead_letter_message", None)
+        if dead_letter is not None:
+            dead_letter(message.handle, reason=reason, error_description=description)
+            return
+        self.abandon(message)
+
     def close(self) -> None:  # pragma: no cover - resource cleanup
         for resource in (*self._senders.values(), *self._receivers.values(), self._client):
             try:

{babelqueue-1.23.0 → babelqueue-1.24.0}/src/babelqueue/sqs_transport.py

@@ -25,6 +25,10 @@ contract keys win a collision, and the merge is bounded by SQS's 10-attribute li
 non-``bq-`` attributes back onto :attr:`~babelqueue.transport.ReceivedMessage.headers`. The frozen
 envelope is untouched (GR-1).
 
+A version-gated message (``bq-schema-version`` the consumer does not support) or a poison body is, with
+dead-lettering off, not deleted: :meth:`SqsTransport.settle_native` leaves it to SQS (visibility
+expiry, then the queue's ``RedrivePolicy``; ADR-0037).
+
 This implements §3 of the broker-bindings contract. The envelope is unchanged
 (``schema_version`` stays 1); SQS is purely additive.
 
@@ -365,6 +369,31 @@ class SqsTransport(Transport):
             QueueUrl=self._resolve_url(message.queue), ReceiptHandle=message.handle
         )
 
+    def dead_letter_queue_name(self, queue: str, suffix: Optional[str] = None) -> str:
+        """:class:`~babelqueue.transport.DeadLetterNamer`: the BabelQueue DLQ of an SQS queue is
+        ``<queue>-dlq`` by default and, for a FIFO queue, ``<queue>-dlq.fifo``. An explicit ``suffix``
+        (``dead_letter_suffix``; ``None``/empty = none) replaces ``-dlq`` and is placed before
+        ``.fifo`` as well: an SQS FIFO queue name must end in ``.fifo``, so ``orders.fifo`` + ``-x`` is
+        ``orders-x.fifo``, never ``orders.fifo-x``. An SQS queue name may hold only alphanumerics,
+        hyphens and underscores (plus that one ``.fifo`` suffix), so the runtime-wide ``<queue>.dlq``
+        cannot be created on SQS (ADR-0037 decision 7). An explicit ``dead_letter_queue`` overrides it."""
+        suffix = suffix or "-dlq"
+        if queue.endswith(".fifo"):
+            return queue[: -len(".fifo")] + suffix + ".fifo"
+        return queue + suffix
+
+    def settle_native(self, message: ReceivedMessage, reason: str, description: str) -> None:
+        """Leave ``message`` to SQS itself (:class:`~babelqueue.transport.NativeSettler`, ADR-0037
+        decisions 1 and 2): a version-gated delivery or a poison body that the runtime may neither
+        process nor drop, with dead-lettering off. Deliberately does nothing on the wire: no
+        ``DeleteMessage``, no ``ChangeMessageVisibility``, no re-send. The message becomes visible
+        again when its visibility timeout lapses (the gate or the poison check rejects it again) and
+        the queue's ``RedrivePolicy`` moves it to the native DLQ once ``maxReceiveCount`` is reached;
+        without a ``RedrivePolicy`` it is redelivered until the retention period ends. The runtime
+        has already logged the event."""
+        if message.handle:
+            self._uncounted_handles.discard(message.handle)
+
     def redeliver(self, message: ReceivedMessage, body: str, delay: float) -> None:
         """Release ``message`` for redelivery after ``delay`` seconds (broker-bindings.md §3.5;
         :class:`~babelqueue.transport.Redeliverer`).

{babelqueue-1.23.0 → babelqueue-1.24.0}/src/babelqueue/transport.py

@@ -229,6 +229,59 @@ class Rewinder(Protocol):
         ...
 
 
+@runtime_checkable
+class DeadLetterNamer(Protocol):
+    """Optional :class:`Transport` capability: the name of the BabelQueue dead-letter queue for a
+    source queue, for a broker whose queue-name rules the runtime-wide ``<queue><suffix>`` shape cannot
+    satisfy. The runtime asks it whenever ``dead_letter_queue`` is not set, passing ``dead_letter_suffix``
+    (``None`` when not set). Amazon SQS implements it (a queue name cannot contain a dot and a FIFO name
+    must end in ``.fifo``): the default is ``<queue>-dlq``, FIFO ``<queue>-dlq.fifo``, and an explicit
+    suffix goes before ``.fifo`` too (``orders.fifo`` + ``-x`` -> ``orders-x.fifo``), never after it
+    (ADR-0037 decision 7). A transport without it keeps ``<queue><suffix>`` with the default ``.dlq``."""
+
+    def dead_letter_queue_name(self, queue: str, suffix: Optional[str] = None) -> str:
+        """The dead-letter queue name for ``queue`` (``suffix`` is the explicit one, or ``None``)."""
+        ...
+
+
+@runtime_checkable
+class Abandoner(Protocol):
+    """Optional :class:`Transport` capability: hand an unsettled *version-gated* delivery back to the
+    broker at once (Azure Service Bus ``Abandon``; broker-bindings.md section 4.5 "A failed write
+    ``Abandon``s it"; ADR-0037 decision 1 rule 5).
+
+    The runtime calls :meth:`abandon` only when the dead-letter write of a version-gated delivery
+    failed, instead of leaving it locked until the lock lapses. It is deliberately narrower than
+    :class:`Rewinder`: a transport that offers only this capability keeps its previous graceful
+    shutdown release and retry re-publish failure handling (copy re-publish and ack)."""
+
+    def abandon(self, message: ReceivedMessage) -> None:
+        """Release the broker lock on ``message`` so the broker redelivers it right away."""
+        ...
+
+
+@runtime_checkable
+class NativeSettler(Protocol):
+    """Optional :class:`Transport` capability: leave a delivery the runtime can neither process nor
+    safely drop to the broker's own mechanism, without acknowledging or deleting it and without
+    re-publishing or retrying it (ADR-0037 decisions 1 and 2).
+
+    The runtime calls :meth:`settle_native` instead of acknowledging when dead-lettering is off (and
+    the strategy is neither ``delete`` nor a writable ``dead_letter``) for a version-gated delivery
+    (broker-bindings.md section 5.7 rule 3) and for a poison body (error-handling.md section 7).
+    SQS implements it as "do nothing" (no ``DeleteMessage``: visibility expiry redelivers the message
+    and the queue's ``RedrivePolicy`` moves it to the native DLQ after ``maxReceiveCount``); Azure
+    Service Bus implements it with an explicit native ``DeadLetter(reason, description)`` into
+    ``$DeadLetterQueue``. The body is never altered. A transport that does not implement it keeps
+    the previous settle (acknowledge and drop), so the behaviour follows the capability, never the
+    transport's name."""
+
+    def settle_native(self, message: ReceivedMessage, reason: str, description: str) -> None:
+        """Leave ``message`` to the broker's native mechanism; ``reason`` and ``description`` say
+        why (e.g. ``"unsupported schema version"``, ``"poison"``)."""
+        ...
+
+
 #: Reserved ``route_urn`` of a record whose envelope carries a non-numeric ``attempts`` (a foreign
 #: producer). It sits under the version-gated prefix, so the runtime dead-letters it directly, raw
 #: and never retried (retrying needs a numeric attempt counter); ``redrive`` restores it to the DLQ

babelqueue-1.24.0/tests/conformance/CONFORMANCE_VERSION

@@ -0,0 +1 @@
+1.8.0