feat: graceful shutdown, SQS release via ChangeMessageVisibility, forbidden-key drop (1.14.0)

Add graceful shutdown to BabelQueue.consume() with a shutdown timeout and
stop(), a Redeliverer protocol for native releases, and conformance
runners for the new manifest sections. SQS retries, unknown-URN releases
and shutdown releases always use ChangeMessageVisibility with a 0 s
default delay; a RedrivePolicy is recommended against poison loops.
The five forbidden envelope keys are dropped on decode and encode with a
warning, transport header projections go through parse_envelope without
false warnings, and a failed acknowledgement after a successful handler
is logged instead of being treated as a handler failure.

Author: muhammetsafak

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

CHANGELOG.md

@@ -9,6 +9,55 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-10-01
+
+### Added
+- **Graceful shutdown** of `BabelQueue.consume()`: on SIGTERM/SIGINT the loop sets a stop flag,
+  takes no new message, lets the in-flight handler finish (or releases the message unchanged once
+  the new `shutdown_timeout` — default 30 s — expires), restores the previous signal handlers and
+  closes the transport. Handlers are installed only on the main thread (`handle_signals=False`
+  opts out); a second signal forces an immediate exit with the message released. A plain
+  `KeyboardInterrupt` keeps its previous behaviour. New `BabelQueue.stop()` ends the loop from any
+  thread after the in-flight message.
+- `Redeliverer` protocol (`redeliver(message, body, delay)`) — a transport's native
+  release; the runtime uses it for retries, unknown-URN `RELEASE` and shutdown releases, and
+  falls back to publish + ack otherwise. New `retry_backoff` / `unknown_urn_release_delay`
+  settings feed its delay.
+- Conformance runners for the `roundtrip`, `data_shape`, `forbidden_keys` and
+  `payload_schema_unicode` sections (none skipped).
+- `.github/dependabot.yml` (pip + GitHub Actions, weekly).
+
+### Changed
+- **SQS release** (broker-bindings §3.5): retries, unknown-URN `RELEASE` and shutdown releases
+  **always** call `ChangeMessageVisibility` instead of re-sending, so the broker's
+  `ApproximateReceiveCount` carries the attempt count. There is no send + delete fallback. The
+  default delay for `retry_backoff` and `unknown_urn_release_delay` is **0 s** (immediate
+  redelivery); a delay outside 0..43200 s (including `inf`/`nan`) is clamped with a warning on the
+  `babelqueue.sqs` logger. A message without a receipt handle is not released (warning); one
+  without a receive count is released but its attempts cannot advance (warning).
+  **Poison-loop risk:** a message that always fails is redelivered immediately until
+  `max_attempts` — configure a native SQS `RedrivePolicy` (`maxReceiveCount` ≥ `max_attempts`) as
+  the backstop and a non-zero `retry_backoff` where needed. A shutdown release also counts as a
+  receive on SQS, so keep `shutdown_timeout` above the longest handler time.
+- Delivery semantics are documented as **at-least-once**: a handler that finishes right as the
+  shutdown deadline fires may be released and run again.
+- The SQS, Kafka, Pulsar, Azure Service Bus and Artemis transports' header/property projections
+  read the envelope without logging a false forbidden-key drop (the body is sent unchanged).
+
+### Fixed
+- The five forbidden envelope keys (`timestamp`, `meta.max_retries`, `meta.attempts`,
+  `meta.source`, `meta.ts` — message-envelope §10) are dropped on decode with a warning on the
+  `babelqueue.codec` logger, and never written on encode. **Transitional:** encode currently drops
+  them with a warning; a future MINOR (K-15 / R1-E0) will reject them instead. A raw-body release
+  republish now strips them too (a clean body is re-sent byte for byte); DLQ redrive still restores
+  the original bytes unchanged.
+- `BabelQueue.stop()` called before `consume()` starts is now honoured instead of being cleared.
+- A failed acknowledgement of an already-processed message (e.g. SQS `DeleteMessage` after a
+  successful handler, an unknown-URN `DELETE`, or a dead-letter publish) is no longer treated as a
+  handler failure: the message is **not** released or retried; the failure is logged at `ERROR`
+  on the new `babelqueue.app` logger and the broker redelivers it on its own (SQS: after the
+  visibility timeout). The consume loop keeps running.
+
 ## [1.13.0] - 2026-06-21
 
 ### Added

README.md

@@ -120,6 +120,27 @@ app.run()                               # consume forever (Ctrl-C to stop)
   and `memory://` (in-process, great for tests/local). Bring your own by passing
   `transport=...`.
 
+- **Graceful shutdown:** SIGTERM/SIGINT finish the in-flight handler, or release
+  the message unchanged once `shutdown_timeout` expires. Delivery is
+  **at-least-once** — keep handlers idempotent (see the idempotency helper).
+
+### SQS release and poison messages
+
+On a handler failure, unknown-URN `release` or shutdown release, the SQS
+transport **always** releases with `ChangeMessageVisibility` (broker-bindings
+§3.5) — it never re-sends a copy. The broker's `ApproximateReceiveCount` is the
+attempt counter, so a shutdown release also consumes an attempt. The default
+delay is **0 s** (`retry_backoff` / `unknown_urn_release_delay`), i.e. the
+message is visible again immediately; delays outside 0..43200 s are clamped with
+a warning.
+
+**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
+queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
+handler's dependencies need time to recover.
+
 ### Sharing a Redis queue with Laravel
 
 By default the Redis transport owns its queue end-to-end (`RPUSH` to produce;

pyproject.toml

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

src/babelqueue/__init__.py

@@ -29,9 +29,9 @@
 from .exceptions import BabelQueueError, DecryptError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
-from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Transport
+from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Redeliverer, Transport
 
-__version__ = "1.13.0"
+__version__ = "1.14.0"
 
 __all__ = [
     "BabelQueue",
@@ -45,6 +45,7 @@
     "InMemoryTransport",
     "ReceivedMessage",
     "HeaderPublisher",
+    "Redeliverer",
     "BabelQueueError",
     "UnknownUrnError",
     "DecryptError",