babelqueue 1.19.0__tar.gz → 1.21.0__tar.gz

{babelqueue-1.19.0 → babelqueue-1.21.0}/.github/workflows/ci.yml

@@ -160,18 +160,45 @@ jobs:
         run: pytest tests/test_kafka_integration.py -v
 
   conformance:
-    name: Conformance suite in sync
+    name: Conformance suite in sync + results.json
     runs-on: ubuntu-latest
+    env:
+      # The pinned conformance release (ADR-0032). Bump together with tests/conformance/.
+      BQ_CONFORMANCE_VERSION: 1.5.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
     steps:
       - uses: actions/checkout@v7
-      - name: Verify vendored conformance matches the canonical suite
+
+      - name: Setup Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Verify the vendored suite against the release asset
         run: |
-          git clone --depth 1 --branch v1.2.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"
-          diff -ru "$RUNNER_TEMP/conformance/schema"        "tests/conformance/schema"
-          echo "Vendored conformance is in sync with the canonical suite."
+          # fetch.sh comes from the pinned tag; it downloads babelqueue-conformance-<v>.tar.gz,
+          # verifies it against the release SHA256SUMS before unpacking, then diffs the vendor dir.
+          curl -fsSL -o "$RUNNER_TEMP/fetch.sh" \
+            "https://raw.githubusercontent.com/BabelQueue/conformance/v${BQ_CONFORMANCE_VERSION}/fetch.sh"
+          echo "${BQ_FETCH_SH_SHA256}  $RUNNER_TEMP/fetch.sh" | sha256sum -c -
+          bash "$RUNNER_TEMP/fetch.sh" --check "$BQ_CONFORMANCE_VERSION" tests/conformance
+          test "$(tr -d '[:space:]' < tests/conformance/CONFORMANCE_VERSION)" = "$BQ_CONFORMANCE_VERSION"
+          echo "Vendored conformance is in sync with the v${BQ_CONFORMANCE_VERSION} release asset."
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,celery,django,otel]" opentelemetry-sdk jsonschema
+
+      - name: Run the conformance suite and write results.json
+        env:
+          BQ_CONFORMANCE_RESULTS: ${{ runner.temp }}/results.json
+        run: pytest -q tests/test_conformance.py
+
+      - name: Validate results.json (schema, bindings, sections)
+        run: python scripts/check_conformance_results.py "$RUNNER_TEMP/results.json" tests/conformance
 
   ci-green:
     name: CI green

babelqueue-1.21.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build, test & publish to PyPI
+    runs-on: ubuntu-latest
+    # Recommended for PyPI Trusted Publishing — configure a "pypi" environment +
+    # a trusted publisher on PyPI (repo BabelQueue/babelqueue-python, this workflow).
+    environment: pypi
+    env:
+      # The pinned conformance release (ADR-0032). Keep identical to ci.yml.
+      BQ_CONFORMANCE_VERSION: 1.5.0
+      BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849
+    permissions:
+      id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed
+      contents: write   # create the GitHub release
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Verify the vendored suite against the release asset
+        run: |
+          curl -fsSL -o "$RUNNER_TEMP/fetch.sh" \
+            "https://raw.githubusercontent.com/BabelQueue/conformance/v${BQ_CONFORMANCE_VERSION}/fetch.sh"
+          echo "${BQ_FETCH_SH_SHA256}  $RUNNER_TEMP/fetch.sh" | sha256sum -c -
+          bash "$RUNNER_TEMP/fetch.sh" --check "$BQ_CONFORMANCE_VERSION" tests/conformance
+          test "$(tr -d '[:space:]' < tests/conformance/CONFORMANCE_VERSION)" = "$BQ_CONFORMANCE_VERSION"
+
+      - name: Install & test (writes results.json)
+        env:
+          BQ_CONFORMANCE_RESULTS: ${{ runner.temp }}/results.json
+        run: |
+          python -m pip install --upgrade pip build
+          pip install -e ".[dev,celery,django,otel]" opentelemetry-sdk jsonschema
+          pytest
+          test -s "$BQ_CONFORMANCE_RESULTS"  # the conformance run must have produced results.json
+
+      - name: Validate results.json (schema, bindings, sections)
+        run: python scripts/check_conformance_results.py "$RUNNER_TEMP/results.json" tests/conformance
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Or, with a token instead of trusted publishing:
+        #   with:
+        #     password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: ${{ runner.temp }}/results.json
+          fail_on_unmatched_files: true

{babelqueue-1.19.0 → babelqueue-1.21.0}/CHANGELOG.md

@@ -9,6 +9,63 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.21.0] - 2026-10-19
+
+Implements ADR-0032 (conformance packaging, results format, ASCII trim and the non-string `job` rule).
+The envelope stays at `schema_version: 1`.
+
+### Changed
+- **`EnvelopeCodec.decode` raises `BabelQueueError` for a JSON object with neither a valid string `job` nor
+  a valid string `urn`** (ADR-0032 section 6). Malformed or non-object input still yields `{}`. The runtime
+  dispatch, the transports' attempts reconciliation and `redrive` use the new `decode_lenient`, so such a
+  body still takes the poison / pass-through path.
+- A non-string `job` (`None`, number, boolean, object, array, falsy or not) is ignored with a warning and a
+  valid string `urn` takes over.
+- Trim and blank checks in `make` (`urn`, `trace_id`) and `accepts` (`trace_id`) use the closed ASCII set
+  (space, `\t`, `\n`, `\v`, `\f`, `\r`); `str.strip()` Unicode whitespace is no longer trimmed
+  (ADR-0032 section 5). The set is exported as `codec.ASCII_WHITESPACE` and the transports import it.
+
+### Added
+- `EnvelopeCodec.decode_lenient`.
+- Conformance runner covers the v1.5.0 sections and writes `results.json` (ADR-0032 section 2).
+  `conformance-known-gaps.json` and `scripts/check_conformance_results.py` gate it in CI and release: the
+  SQS `delay` and Kafka `backoff` tier cases run and record honest `fail`s until they are implemented.
+
+## [1.20.0] - 2026-10-17
+
+Conformance suite 1.4.0, [ADR-0031](https://babelqueue.com). The envelope is unchanged
+(`schema_version: 1`); this is a MINOR with one deliberate behaviour change (encode rejects).
+
+### Added
+- `EnvelopeCodec.make(urn, data, *, queue, trace_id, meta=None)`: a producer `meta` write API. The entries
+  land in `meta` next to the core keys (recommended shape `meta.ext.<vendor>`). A collision with a core
+  meta key or a forbidden key raises the new `EnvelopeKeyError` (subclass of `BabelQueueError`, with a
+  `pointer` attribute). `_envelope_shape.CORE_META_KEYS` is the single copy of the core key list.
+- `decode` folds the `urn` alias into `job` (ADR-0031 (c)): a `job` that is missing, empty or only ASCII
+  whitespace (`" \t\n\v\f\r"`; a U+2003 `job` is NOT blank) falls back to `urn` silently; when both carry
+  a value, `job` wins and `urn` is dropped with a warning naming `/urn`. `accepts()` / `urn()` follow the
+  same rule. The decoded envelope never keeps a `urn` key.
+- Tests: the runner now implements the 1.4.0 fields (`expect_preserved` on `forbidden_keys`;
+  `expect_absent_after_reencode`, `apply_dead_letter`, `expect_dead_letter` on `roundtrip`, the latter via
+  `dead_letter.annotate`) plus the `extension_write` and `encode_reject` sections, with a runner
+  self-test proving violations are reported.
+
+### Changed
+- **Behaviour change: `EnvelopeCodec.encode` raises `EnvelopeKeyError`** for an envelope carrying a
+  forbidden key (message-envelope.md section 10) or a top-level `urn`, instead of dropping it with a
+  warning (policy K-15 (a)). Nothing is written. `decode` still warns and drops, so re-encoding a decoded
+  envelope is safe. Code that built an envelope from a raw legacy body and relied on encode to clean it
+  must decode it first (`EnvelopeCodec.encode(EnvelopeCodec.decode(raw))`).
+- `test_all_five_contract_keys_are_covered` is a subset check (the suite adds `/urn` cases).
+- Docs only: the note in the previous release that the Go reference's case-insensitive envelope-key read "is tightened separately" is now closed — Go core 1.14.0 reads envelope keys exactly (case-sensitive, last duplicate wins), so every SDK now decides poison on the same exact-case keys.
+
+### Fixed
+- Raw-body re-encode paths now decode before they encode, so the new `encode` rejection cannot strand a
+  legacy body: the runtime's raw-body RELEASE re-publish (`app.py`), and the SQS and Pulsar attempts
+  reconciliation (Kafka, Azure Service Bus and Artemis already decoded first). A body with a legacy
+  `timestamp` or only a `urn` alias is re-emitted normalised (forbidden key dropped and warned, `urn`
+  folded into `job`); unknown top-level and `meta` keys, including `meta.ext`, are preserved.
+
 ## [1.19.0] - 2026-10-12
 
 ### Changed

{babelqueue-1.19.0 → babelqueue-1.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.19.0
+Version: 1.21.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
@@ -58,6 +58,8 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/babelqueue.svg)](https://pypi.org/project/babelqueue/)
 [![Python](https://img.shields.io/pypi/pyversions/babelqueue.svg)](https://pypi.org/project/babelqueue/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Live interop](https://img.shields.io/endpoint?url=https%3A%2F%2Fbabelqueue.com%2Fbadges%2Fnightly.json)](https://babelqueue.com/compatibility/)
+[![BabelQueue conformance](https://img.shields.io/badge/BabelQueue-conformance%20matrix-10B981.svg)](https://babelqueue.com/compatibility/)
 
 > **Polyglot Queues, Simplified.** Read and write the canonical BabelQueue message
 > envelope from Python — so your Python services (AI/ML, data processing, …)
@@ -106,6 +108,29 @@ The envelope is identical to every other SDK's:
 }
 ```
 
+### Extension metadata, forbidden keys and the `urn` alias (1.20.0, ADR-0031)
+
+```python
+# Producer meta: extra keys next to the core meta keys (recommended shape: meta.ext.<vendor>).
+envelope = EnvelopeCodec.make(
+    "urn:babel:orders:created", {"order_id": 1042},
+    queue="orders", meta={"ext": {"acme": {"tier": "gold"}}},
+)
+```
+
+- `meta=` is keyword-only. A key that collides with a core meta key (`id`, `queue`, `lang`,
+  `schema_version`, `created_at`) or with a forbidden key (`max_retries`, `attempts`, `source`, `ts`)
+  raises `EnvelopeKeyError` (a `BabelQueueError`; its `pointer` names the key, e.g. `/meta/ts`).
+- Unknown top-level and `meta` keys of an inbound message survive a decode -> `attempts + 1` -> encode
+  hop (retry, redrive, dead-letter), so a vendor `meta.ext` block is never lost.
+- `EnvelopeCodec.encode` **rejects** an envelope that carries a forbidden key (top-level `timestamp`;
+  `meta.max_retries`, `meta.attempts`, `meta.source`, `meta.ts`) or the inbound-only top-level `urn`
+  alias: it raises `EnvelopeKeyError` instead of dropping the key with a warning. `decode` is unchanged
+  (it still warns and drops), so a decoded envelope can always be re-encoded.
+- `decode` folds `urn` into `job`: a `job` that is missing, empty or only ASCII whitespace (space, `\t`,
+  `\n`, `\v`, `\f`, `\r`) falls back to `urn`; when both carry a value, `job` wins and `urn` is dropped
+  with a warning naming `/urn`. The decoded envelope never keeps a `urn` key.
+
 ### Typed messages (optional)
 
 ```python

{babelqueue-1.19.0 → babelqueue-1.21.0}/README.md

@@ -4,6 +4,8 @@
 [![PyPI](https://img.shields.io/pypi/v/babelqueue.svg)](https://pypi.org/project/babelqueue/)
 [![Python](https://img.shields.io/pypi/pyversions/babelqueue.svg)](https://pypi.org/project/babelqueue/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Live interop](https://img.shields.io/endpoint?url=https%3A%2F%2Fbabelqueue.com%2Fbadges%2Fnightly.json)](https://babelqueue.com/compatibility/)
+[![BabelQueue conformance](https://img.shields.io/badge/BabelQueue-conformance%20matrix-10B981.svg)](https://babelqueue.com/compatibility/)
 
 > **Polyglot Queues, Simplified.** Read and write the canonical BabelQueue message
 > envelope from Python — so your Python services (AI/ML, data processing, …)
@@ -52,6 +54,29 @@ The envelope is identical to every other SDK's:
 }
 ```
 
+### Extension metadata, forbidden keys and the `urn` alias (1.20.0, ADR-0031)
+
+```python
+# Producer meta: extra keys next to the core meta keys (recommended shape: meta.ext.<vendor>).
+envelope = EnvelopeCodec.make(
+    "urn:babel:orders:created", {"order_id": 1042},
+    queue="orders", meta={"ext": {"acme": {"tier": "gold"}}},
+)
+```
+
+- `meta=` is keyword-only. A key that collides with a core meta key (`id`, `queue`, `lang`,
+  `schema_version`, `created_at`) or with a forbidden key (`max_retries`, `attempts`, `source`, `ts`)
+  raises `EnvelopeKeyError` (a `BabelQueueError`; its `pointer` names the key, e.g. `/meta/ts`).
+- Unknown top-level and `meta` keys of an inbound message survive a decode -> `attempts + 1` -> encode
+  hop (retry, redrive, dead-letter), so a vendor `meta.ext` block is never lost.
+- `EnvelopeCodec.encode` **rejects** an envelope that carries a forbidden key (top-level `timestamp`;
+  `meta.max_retries`, `meta.attempts`, `meta.source`, `meta.ts`) or the inbound-only top-level `urn`
+  alias: it raises `EnvelopeKeyError` instead of dropping the key with a warning. `decode` is unchanged
+  (it still warns and drops), so a decoded envelope can always be re-encoded.
+- `decode` folds `urn` into `job`: a `job` that is missing, empty or only ASCII whitespace (space, `\t`,
+  `\n`, `\v`, `\f`, `\r`) falls back to `urn`; when both carry a value, `job` wins and `urn` is dropped
+  with a warning naming `/urn`. The decoded envelope never keeps a `urn` key.
+
 ### Typed messages (optional)
 
 ```python

babelqueue-1.21.0/conformance-known-gaps.json

@@ -0,0 +1,84 @@
+{
+  "gaps": [
+    {
+      "section": "delay",
+      "case": "standard-1s",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "delay",
+      "case": "standard-60s",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "delay",
+      "case": "standard-900s-is-the-cap",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "delay",
+      "case": "standard-901s-rejected",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "delay",
+      "case": "standard-3600s-rejected",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "delay",
+      "case": "fifo-per-message-delay-rejected",
+      "reason": "Python SqsTransport has no per-message DelaySeconds publish path (broker-bindings section 3.4, ADR-0012); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "below-first-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "exactly-first-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "just-above-first-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "exactly-third-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "exactly-largest-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "above-largest-tier-rejected",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "no-tiers-configured-rejected",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "retry_republish/first-retry",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "retry_republish/third-retry-picks-larger-tier",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    },
+    {
+      "section": "backoff",
+      "case": "retry_republish/no-tiers-configured-rejected",
+      "reason": "Python KafkaTransport has no retry-topic tier routing (broker-bindings sections 6.4/6.5, ADR-0015); not implemented in this core, tracked in the r1 follow-up plan"
+    }
+  ]
+}

{babelqueue-1.19.0 → babelqueue-1.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.19.0"
+version = "1.21.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.21.0/scripts/check_conformance_results.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Completeness gate for a conformance ``results.json`` (ADR-0032 section 3 / Compliance).
+
+Usage: python scripts/check_conformance_results.py <results.json> <conformance-dir> [src-dir]
+
+Known gaps: a ``fail`` is accepted only when ``conformance-known-gaps.json`` (repo root) lists its
+section and case; a listed case that reports ``pass`` is a stale gap and fails the gate, as does
+a ``skip`` or a missing result for a listed case, and a gap naming a case the manifest lacks.
+
+Shared by ``ci.yml`` and ``release.yml`` so a tag cannot publish an asset CI would have refused.
+It is deliberately independent of the test runner: the carried bindings are re-derived from the
+package modules and compared for *set equality* with ``results.bindings`` (a missing binding and
+a surplus one both fail), then the sections are checked against the manifest scopes.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+import jsonschema
+
+# Transport module -> binding (manifest scope). Keep in step with tests/test_conformance.py.
+TRANSPORT_BINDINGS = {
+    "redis_transport": "redis",
+    "pika_transport": "amqp",
+    "sqs_transport": "sqs",
+    "asb_transport": "asb",
+    "pulsar_transport": "pulsar",
+    "kafka_transport": "kafka",
+    "artemis_transport": "artemis",
+}
+
+
+def derive_bindings(src: Path) -> set:
+    bindings = set()
+    for path in sorted(src.glob("*_transport.py")):
+        if path.stem not in TRANSPORT_BINDINGS:
+            raise SystemExit(f"transport module {path.name} has no binding mapping")
+        bindings.add(TRANSPORT_BINDINGS[path.stem])
+    otel = src / "otel.py"
+    if otel.is_file() and "traceparent" in otel.read_text(encoding="utf-8").lower():
+        bindings.add("otel")
+    return bindings
+
+
+GAPS_FILE = Path(__file__).resolve().parent.parent / "conformance-known-gaps.json"
+
+#: A reason must cite the contract section and the follow-up plan, so a gap is never anonymous.
+REASON_PATTERN = re.compile(r"section[s]? \d")
+REASON_PLAN = "r1 follow-up plan"
+
+
+def check_gap_entry(entry: dict, manifest: dict) -> list:
+    """Problems with one known-gap entry against the manifest (empty when it is well formed)."""
+    problems = []
+    section, case, reason = entry["section"], entry["case"], entry["reason"]
+    definition = manifest["sections"].get(section)
+    if definition is None:
+        problems.append(f"{section}/{case}: unknown section")
+    elif definition["scope"] == "core":
+        # Only a broker-scoped feature may be a documented gap; the core envelope never is.
+        problems.append(f"{section}/{case}: a core-scope section cannot have a known gap")
+    if not REASON_PATTERN.search(reason) or REASON_PLAN not in reason:
+        problems.append(f'{section}/{case}: reason must cite a contract "section N" and the "{REASON_PLAN}"')
+    return problems
+
+
+def load_gaps(path: Path, errors: list, manifest: dict) -> dict:
+    """``(section, case) -> reason`` from the known-gaps file; malformed entries are errors."""
+    if not path.is_file():
+        return {}
+    document = json.loads(path.read_text(encoding="utf-8"))
+    gaps: dict = {}
+    entry_problems: list = []
+    entries = document.get("gaps") if isinstance(document, dict) else None
+    if not isinstance(entries, list):
+        errors.append(f'{path.name}: top level must be {{"gaps": [...]}}')
+        return gaps
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict) or not all(
+            isinstance(entry.get(key), str) and entry[key].strip() for key in ("section", "case", "reason")
+        ):
+            errors.append(f"{path.name}: gaps[{index}] needs non-empty string section, case and reason")
+            continue
+        key = (entry["section"], entry["case"])
+        entry_problems.extend(check_gap_entry(entry, manifest))
+        if key in gaps:
+            errors.append(f"{path.name}: duplicate gap {key[0]}/{key[1]}")
+        gaps[key] = entry["reason"]
+    errors.extend(f"{path.name}: {problem}" for problem in entry_problems)
+    return gaps
+
+
+def main(argv: list) -> int:
+    if len(argv) not in (2, 3):
+        print(__doc__, file=sys.stderr)
+        return 2
+    results_path, suite = Path(argv[0]), Path(argv[1])
+    src = Path(argv[2]) if len(argv) == 3 else Path("src/babelqueue")
+
+    results = json.loads(results_path.read_text(encoding="utf-8"))
+    manifest = json.loads((suite / "manifest.json").read_text(encoding="utf-8"))
+    schema = json.loads((suite / "schema" / "results.schema.json").read_text(encoding="utf-8"))
+
+    errors = []
+    try:
+        jsonschema.Draft202012Validator(schema, format_checker=jsonschema.FormatChecker()).validate(results)
+    except jsonschema.ValidationError as exc:
+        errors.append(f"results.json does not match results.schema.json: {exc.message}")
+
+    carried = derive_bindings(src)
+    listed = set(results.get("bindings", []))
+    for name in sorted(carried - listed):
+        errors.append(f'binding "{name}" is carried by the package but missing from results.bindings')
+    for name in sorted(listed - carried):
+        errors.append(f'results.bindings lists "{name}", which the package does not carry')
+
+    sections = results.get("sections", {})
+    for name, definition in manifest["sections"].items():
+        in_scope = definition["scope"] == "core" or definition["scope"] in listed
+        if in_scope and name not in sections:
+            errors.append(f'in-scope section "{name}" (scope {definition["scope"]}) is missing')
+        if not in_scope and name in sections:
+            errors.append(f'section "{name}" (scope {definition["scope"]}) must be absent')
+
+    gaps = load_gaps(GAPS_FILE, errors, manifest)
+    for (section, case_id), _reason in sorted(gaps.items()):
+        outcome = sections.get(section, {}).get(case_id)
+        if outcome is None:
+            errors.append(f"{section}/{case_id}: listed as a known gap but absent from results.json")
+        elif outcome.get("status") == "pass":
+            errors.append(f"{section}/{case_id}: stale gap (listed in {GAPS_FILE.name} but passes); remove it")
+        elif outcome.get("status") == "skip":
+            errors.append(f"{section}/{case_id}: a known gap must be reported as fail, not skip")
+
+    failed = []
+    for section, cases in sections.items():
+        for case_id, outcome in cases.items():
+            if outcome.get("status") == "fail" and (section, case_id) not in gaps:
+                failed.append(f"{section}/{case_id}")
+    errors.extend(f"{case}: fail (not a known gap)" for case in failed)
+
+    if errors:
+        print("\n".join(errors), file=sys.stderr)
+        return 1
+    known = sum(
+        1
+        for section, cases in sections.items()
+        for case_id, outcome in cases.items()
+        if outcome.get("status") == "fail" and (section, case_id) in gaps
+    )
+    print(f"results.json complete: bindings={sorted(listed)}, sections={len(sections)}, fail={known} (all known gaps)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

{babelqueue-1.19.0 → babelqueue-1.21.0}/src/babelqueue/__init__.py

@@ -41,7 +41,7 @@ from .transport import (
     Transport,
 )
 
-__version__ = "1.19.0"
+__version__ = "1.21.0"
 
 __all__ = [
     "BabelQueue",

{babelqueue-1.19.0 → babelqueue-1.21.0}/src/babelqueue/_envelope_shape.py

@@ -51,6 +51,9 @@ _META = {
     "schema_version": _INTEGER,
     "created_at": _INTEGER,
 }
+#: The core ``meta`` keys of message-envelope.md section 4 (the single copy; the producer ``meta``
+#: write API of the codec rejects a collision with any of them, ADR-0031 (b)).
+CORE_META_KEYS = frozenset(_META)
 _DEAD_LETTER = {
     "reason": _STRING,
     "error": _STRING,

{babelqueue-1.19.0 → babelqueue-1.21.0}/src/babelqueue/app.py

@@ -284,7 +284,7 @@ class BabelQueue:
             # §3.7/§4.7/§5.7/§6.7/§7.7): the raw body goes to the DLQ byte-identical, so there is
             # no envelope to read here.
             gated = received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX)
-            envelope = {} if gated else EnvelopeCodec.decode(received.body)
+            envelope = {} if gated else EnvelopeCodec.decode_lenient(received.body)
             urn = str(envelope.get("job") or envelope.get("urn") or "")
             if received.route_urn and envelope:
                 # Transport-supplied routing override; body untouched. Only for a body that
@@ -458,8 +458,9 @@ class BabelQueue:
         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
+        """Release a message whose handler never completed (shutdown): unchanged body
+        (normalised only if it carries a forbidden key or a ``urn`` alias), no backoff, and the
+        runtime adds no ``attempts`` increment. A broker that counts
         deliveries still counts it: on SQS the release bumps ``ApproximateReceiveCount``, so the
         redelivered envelope reads one more attempt (and a ``RedrivePolicy`` sees it too)."""
         self._release(received, received.body, 0.0)
@@ -578,12 +579,15 @@ _UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 def _without_forbidden_keys(body: str) -> str:
     """``body`` unchanged, unless it carries a forbidden envelope key (message-envelope.md §10,
-    e.g. from a legacy producer) — then it is re-encoded without it (warned by the codec), so a
+    e.g. from a legacy producer) or a ``urn`` alias — then it is re-encoded without it (warned by the codec), so a
     raw-body re-publish never re-emits a key the decode boundary reported as dropped."""
     parsed = parse_envelope(body)
-    if not parsed or not has_forbidden_keys(parsed):
+    # ``urn`` is not a §10 key but ``encode`` rejects it and ADR-0031 (a)/(c) forbid re-emitting it.
+    if not parsed or not (has_forbidden_keys(parsed) or "urn" in parsed):
         return body
-    return EnvelopeCodec.encode(parsed)
+    # ``decode`` (not the raw parse) so the dropped keys — and a top-level ``urn`` alias, folded
+    # into ``job`` — are gone before ``encode``, which rejects them (ADR-0031 (c)).
+    return EnvelopeCodec.encode(EnvelopeCodec.decode_lenient(body))
 
 
 def _handler_wants_envelope(fn: Handler) -> bool:

{babelqueue-1.19.0 → babelqueue-1.21.0}/src/babelqueue/artemis_transport.py

@@ -37,7 +37,7 @@ import re
 from typing import Any, Dict, Optional
 from urllib.parse import quote
 
-from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .codec import ASCII_WHITESPACE, SCHEMA_VERSION, EnvelopeCodec, parse_envelope
 from .transport import ReceivedMessage, Transport, truncate_declared_version
 
 _logger = logging.getLogger("babelqueue.artemis")
@@ -45,7 +45,7 @@ _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]*")
+_BLANK_ASCII_PATTERN = re.compile("[" + re.escape(ASCII_WHITESPACE) + "]*")
 #: 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 dead-letters it
 #: directly (never retried, never decoded; the DLQ record is the incoming raw body). The
@@ -188,7 +188,7 @@ class ArtemisTransport(Transport):
             return body
         if dc <= 0:
             return body
-        env = EnvelopeCodec.decode(body)
+        env = EnvelopeCodec.decode_lenient(body)
         if not env or dc <= int(env.get("attempts", 0) or 0):
             return body
         env["attempts"] = dc

{babelqueue-1.19.0 → babelqueue-1.21.0}/src/babelqueue/asb_transport.py

@@ -28,7 +28,7 @@ import re
 from typing import Any, Dict, Optional
 from urllib.parse import quote, urlsplit
 
-from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .codec import ASCII_WHITESPACE, SCHEMA_VERSION, EnvelopeCodec, parse_envelope
 from .transport import ReceivedMessage, Transport, truncate_declared_version
 
 _logger = logging.getLogger("babelqueue.asb")
@@ -36,7 +36,7 @@ _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]*")
+_BLANK_ASCII_PATTERN = re.compile("[" + re.escape(ASCII_WHITESPACE) + "]*")
 #: 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 dead-letters it
 #: directly (never retried, never decoded; the DLQ record is the incoming raw body). The
@@ -149,7 +149,7 @@ class AsbTransport(Transport):
         if dc <= 1:
             return body
         native = dc - 1
-        env = EnvelopeCodec.decode(body)
+        env = EnvelopeCodec.decode_lenient(body)
         if not env or native <= int(env.get("attempts", 0)):
             return body
         env["attempts"] = native