diff --git a/AGENTS.md b/AGENTS.md
index 2ce11e5..9a2d212 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,7 +41,7 @@ Guidance for any agent (or human) working in this repo. `CLAUDE.md` is a symlink
 2. **Fixture-semantics** — *"does this fixture actually test what it claims?"* See the **Fixture quality bar** in `fixtures/asyncapi/README.md` (no vacuous values; claim↔content; full-path/both-direction coverage; internal consistency; negative cases). The validity-only angle misses all of these.
 
 ## Status & next
-All build tiers and v1 gates are `tested` (34 of 36 requirements): `model` → `broker`/`registry`/`ingestion` → `engine`/`validation` → `scenarios`/`control-plane` → `cli` (the full verb set incl. `up`/`down` process management over the G14 runfile, watch modes, `init`), plus the four cross-cutting v1 gates (R-028–R-031). The open items: the two empirical spikes, `R-006` (WS-fidelity) and `R-007` (capture the browser application's `connect()`), which need the real browser application against `broker/`'s Aedes defaults and are hard gates on calling v1 done; plus `R-033` (`tested`): the `demo-app/` spike-harness webapp + connect fingerprint (`docs/specs/demo-app.md`), which rehearses both spikes — the at-work capture is now a no-app-change procedure (point the real client at offbook, read `offbook logs`). The adoption surface is `tested` (R-034–R-036: README + guides with executable quickstart/cookbook gates, `offbook doctor`, the first-run error audit — docs/specs/adoption.md).
+All build tiers and v1 gates are `tested` (37 of 39 requirements): `model` → `broker`/`registry`/`ingestion` → `engine`/`validation` → `scenarios`/`control-plane` → `cli` (the full verb set incl. `up`/`down` process management over the G14 runfile, watch modes, `init`), plus the four cross-cutting v1 gates (R-028–R-031). The open items: the two empirical spikes, `R-006` (WS-fidelity) and `R-007` (capture the browser application's `connect()`), which need the real browser application against `broker/`'s Aedes defaults and are hard gates on calling v1 done; plus `R-033` (`tested`): the `demo-app/` spike-harness webapp + connect fingerprint (`docs/specs/demo-app.md`), which rehearses both spikes — the at-work capture is now a no-app-change procedure (point the real client at offbook, read `offbook logs`). The adoption surface is `tested` (R-034–R-036: README + guides with executable quickstart/cookbook gates, `offbook doctor`, the first-run error audit — docs/specs/adoption.md). The AsyncAPI support range is declared and hardened (R-037–R-039, D-018): **2.0.0–2.6.0, 3.0.0, 3.1.0**, payloads validated under **draft-07**, with the R-028 gate extended over `multi-format.yaml` (3.1.0) and `v2-oldest.yaml` (2.0.0).
 
 ## Working notes
 - **Git identity is the user's to set** — don't run `git config user.*` on their behalf. Commit/push **only when asked**.
diff --git a/DECISIONS.md b/DECISIONS.md
index 491823c..3ff917b 100644
--- a/DECISIONS.md
+++ b/DECISIONS.md
@@ -44,6 +44,7 @@ Append-only. Each decision has a stable never-reused `D-###` id, what was decide
 **Why**: `@asyncapi/parser` 3.x ships only **draft-07** schema parsers (the AsyncAPI default format and `application/schema+*;version=draft-07`, both draft-07-based); draft-07 ignores `$ref` siblings, so the keyword is normalized away during parse — before Ajv-2020 (which *would* honor it) ever sees the schema. The faithful fix (register a custom 2020-12 pass-through schema parser) is **not a small change**: a naive pass-through collapses the payload model to a **vacuous** schema that accepts everything (probed and confirmed), so it is genuinely spike-shaped. R1 forbids the hand-rolled `$ref`-walking alternative. Shipping the achievable bar plus a pinned tripwire is more honest than a broken fixture (option: leave it unparseable) or holding R-004 open on an unbounded spike (option: spike-A-now); owner chose pragmatic-now.
 **Mitigations / notes**: the external `pattern` **is** inlined + enforced (negative case covered in `src/registry/index.test.ts`); `buildRegistry` gained an optional `source` so cross-file `$ref`s resolve, and parse failures now surface the parser's diagnostics instead of a bare "failed to parse". The tripwire (`external-ref: KNOWN LIMITATION (D-005 …)`) asserts the current drop so the regression is loud, not silent.
 **Obligations (deferred spike)**: register a JSON-Schema-2020-12 schema parser with `@asyncapi/parser` (or equivalent) so `$ref` siblings survive to Ajv-2020; then re-point the tripwire to assert enforcement and revisit §12.4. Until then, the §5 bar's sibling-under-2020-12 clause is explicitly **not** met.
+**Superseded by**: D-018 (2026-07-30). offbook now validates under **draft-07**, the dialect both spec majors declare for the Schema Object and the one the parser emits, so the dropped `$ref` sibling is **dialect-correct behavior rather than a limitation** and the 2020-12 schema-parser spike is no longer an obligation. The tripwire is retained and reworded (`external-ref: a $ref-sibling keyword is not enforced, which is draft-07-correct`) so that a future dialect change, which would start enforcing the sibling, stays loud.
 **From**: R-004 build dialog (2026-07-04), owner chose the pragmatic path over spiking the custom parser now
 **Folds into**: fixtures/asyncapi/external-ref.yaml, fixtures/asyncapi/README.md, src/registry/index.ts (`source` param), src/registry/index.test.ts (tripwire), REQUIREMENTS.md (R-004)
 
@@ -133,3 +134,23 @@ Append-only. Each decision has a stable never-reused `D-###` id, what was decide
 **Why**: The full local gate set existed but nothing enforced it at merge time. One serial job because the whole set runs in ~40 s locally, so parallel jobs would only add per-job runner boot and install overhead. Bun is pinned because the bunfig.toml coverage-gate semantics (per-file floors; silent exit-1 as the only failure signal) were empirically verified on 1.3.14, and a floating runtime could silently change what the test gate means; bumping the pin is a deliberate one-line PR the gates themselves validate. A compiled-binary artifact was dropped after two verified findings (the extensionless `bin/offbook` makes `bun build --compile` emit a 1-module no-op binary, and with that fixed the Spectral/nimma dynamic `require()`s still break the compiled binary at startup: `Cannot find module './impl/format'`); single-binary offbook is deferred as its own project.
 **From**: docs/superpowers/specs/2026-07-30-github-ci-design.md (design dialog, 2026-07-30)
 **Folds into**: .github/workflows/ci.yml, package.json (`typecheck`), AGENTS.md (working notes), README.md (badge)
+
+### D-018: offbook supports AsyncAPI 2.0.0-3.1.0, validates payloads under draft-07, and polices bindings itself
+**Date**: 2026-07-30
+**What**: Declare a tested support matrix (2.0.0-2.6.0, 3.0.0, 3.1.0; 1.x refused), raise the `@asyncapi/parser` floor to `^3.6.0`, gate the version in `registry/` before `parse()`, and harden the shared ingestion path: unwrap the Multi Format Schema Object payload wrapper, validate under JSON Schema draft-07 with an explicit stamp instead of stamping 2020-12, diagnose post-draft-07 keywords, contain Ajv compile failures, validate multi-message operations as `anyOf`, and police mqtt binding values and keys against the official binding schema's key set. Supersedes D-005's deferred 2020-12 obligation.
+**Why**: Three defects were found by research, none by a failing test. A valid 3.x multi-format payload made the channel validator accept everything including `null`, because `BaseModel.json()` returns the wrapper verbatim; that is the false-negative class R-028 exists to prevent. A legal draft-07 tuple schema crashed `bootProject` uncaught, because offbook stamped 2020-12 over a schema the parser emits as draft-07. 2.x maps `mqtt` to an empty schema, so `qos: 9` reached a `Channel` typed `0 | 1 | 2`. Converting 2.x to 3.x on ingest was considered and rejected: the fleet is mostly 3.x, so it would add a dependency and a lossy translation layer to serve a shrinking minority, and it would anchor diagnostics to a document the adopter never wrote. Draft-07 is the dialect BOTH majors declare and the parser actually emits, so validating under it is the root-cause fix and needs no schema rewriting (R1 intact).
+**Mitigations / notes**: Draft-07 silently ignores post-draft-07 keywords, so a dialect-mismatch diagnostic makes that loud. The explicit supported-version list is cross-checked by a test, because deriving it from `@asyncapi/specs` reproduces the trap that fooled parser 3.4.0/3.5.0. New findings reuse the existing closed `spec-load` diagnostic kind with a machine-greppable `detail` prefix rather than expanding the `Diagnostic.kind` union. A 2.x spec authored from the client's perspective still loads inverted and no tool can detect that; it is documented for adopters.
+**Discovered during implementation (2026-07-30)**: **json-schema-faker 0.6.2 cannot draw a valid draft-07 tuple.** Measured over the `{type: array, items: [{type: string}, {type: number}]}` shape: it emits objects with numeric keys (for example `[{"0":"aG88rL","1":441.48}, ...]`) and fails the Ajv recheck **10/10 seeds**, unchanged by `additionalItems` or `minItems`. Consequences: validation of tuples is correct under draft-07 (positional, `additionalItems` honored), but a tuple-shaped `toClient` payload has **no usable L1 fake** and falls to F5 drop-and-surface. The tuple regression case therefore lives as an **inline test spec**, not in `fixtures/asyncapi/`: a tuple fixture would fail the R-027 faker-floor spike and flip **D-008**'s measured verdict ("no §5-bar fixture failed ⇒ F5's drop-and-surface stands and the L1 floor needs no keyed-fallback re-draw"), which is a separate question from the dialect. Whether the L1 floor should gain a keyed-fallback re-draw for shapes json-schema-faker cannot serve is left open, deliberately unresolved here.
+**Obligations**: none deferred.
+**From**: brainstorm dialog 2026-07-30 after a deep-research pass; every behavioral claim verified empirically against the installed toolchain (results tabulated in the design doc).
+**Folds into**: src/model/spec-version.ts, src/registry/index.ts, src/ingestion/index.ts, docs/specs/contracts.md §5/§6, fixtures/asyncapi/, REQUIREMENTS.md (R-037-R-039), DECISIONS.md (D-005 superseded note)
+
+### D-019: the version gate refuses only what it recognizes, and upstream constants are hand-authored behind a drift gate
+**Date**: 2026-08-01
+**What**: Amends D-018 on three mechanisms. (1) The R-037 preflight fires only on a version it positively read and positively recognizes as untested; an unreadable or absent `asyncapi` field falls through to `@asyncapi/parser`, and the refusal message names every tested version instead of a range. (2) The alignment between offbook's supported set and the parser's capability is enforced by an install-time drift test (`test/upstream-drift.test.ts`), not a runtime post-parse recheck. (3) `@asyncapi/specs` becomes a devDependency and the mqtt operation-binding key set becomes a hand-authored constant in `registry/`, transcribed including the `x-` vendor-extension pattern, with the same drift test pinning it and a source-text check keeping it out of `src/`.
+**Why**: Three defects found in PR #2 review. The preflight treated `readSpecVersion`'s `undefined` as "unsupported version", so malformed YAML, an empty file, and a fetched HTML error page all died advising `asyncapi convert`; spec-load failure aborts `up` in the foreground, so that was the whole error an adopter saw, and it fails the R-036 bar of naming what actually failed. The parser's own diagnostics already distinguish those cases precisely, so owning branded messages for them would duplicate correct text and put a second YAML reader in a position to disagree with the parser's. `@asyncapi/specs` was imported but undeclared, a transitive of `@asyncapi/parser` resolved only by flat hoisting, at an unversioned internal subpath the package's absent `exports` map does not guarantee. Deriving the binding key set at runtime also read only `properties`, dropping the schema's `patternProperties` allowance, so a spec-legal `x-vendor-thing` was reported as an unknown key.
+**Mitigations / notes**: A runtime `document.version()` recheck was considered for the gap the preflight leaves (a version the parser accepts and offbook does not) and rejected: it is structurally unreachable while the two sets agree, which they do, so it would ship as a permanently uncovered `throw` under the per-file coverage floor. The drift test catches the same divergence at the dependency bump instead. The re-import guard is a source-text check rather than a Biome `noRestrictedImports` rule because Biome 1.9 matches whole module specifiers: a bare `@asyncapi/specs` entry does not flag `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` (verified both ways), which is precisely the import shape being prevented. The drift test does not reopen what D-018 rejected: the constants stay hand-authored and separately tested against the real parser, and the test only makes upstream drift loud.
+**Discovered during implementation (2026-08-01)**: an unquoted `asyncapi: 2.6` (a YAML float, not a string) makes `@asyncapi/parser` 3.6.0 die inside `getSemver` with a raw `TypeError: undefined is not an object (evaluating 'patchWithRc.split')` stack dumped into a diagnostic. The preflight catches it first because `readSpecVersion` normalizes with `String()`, which retroactively justifies that normalization as load-bearing rather than defensive. That normalization was not yet complete: a present-but-null `asyncapi` field (bare `asyncapi:`) still collapsed to `undefined`, the absent-field case, and fell through to the same parser TypeError. Closed by reading any POSITIVELY PRESENT `asyncapi` value, null included, since the parser's internal TypeError covers null, empty string, boolean, and object values alike, not just the unquoted-float case.
+**Obligations**: none deferred.
+**From**: code review of PR #2 (findings 1-3), then a design dialog on 2026-08-01; every behavioral claim verified empirically against the installed toolchain.
+**Folds into**: src/registry/index.ts, package.json, test/upstream-drift.test.ts, REQUIREMENTS.md (R-037, R-039), docs/specs/build-plan.md §1
diff --git a/README.md b/README.md
index c294ce7..4cd509d 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@ other side of every topic and tells you when either side breaks the contract.
 
 - [Bun](https://bun.sh) >= 1.3 (the `engines.bun` floor in `package.json`)
 - git access to the host your AsyncAPI spec repos live on
+- AsyncAPI specs at **2.0.0-2.6.0, 3.0.0, or 3.1.0** (3.1.0 recommended). AsyncAPI 1.x is not supported: convert it with `asyncapi convert` first.
 
 ## Quickstart (zero config)
 
diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
index b34935e..bba0a0d 100644
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -40,7 +40,7 @@ A browser-style `mqtt.js` client connects to the Aedes ws listener over MQTT 3.1
 **COVERS**: docs/specs/build-plan.md#tier-1
 **IMPL**: src/registry/
 **TEST**: src/registry/index.test.ts
-`registry/` parses every `fixtures/asyncapi/*` (including external-ref, qos-retain, qos-overrides), resolves channel direction (v2 + v3) and the qos/retain precedence chain, and its `match`/`matchesFilter` behave per the §5 correctness bar (the 2020-12 `$ref`-sibling edge is carved out to D-005, pinned by a tripwire test).
+`registry/` parses every `fixtures/asyncapi/*` (including external-ref, qos-retain, qos-overrides), resolves channel direction (v2 + v3) and the qos/retain precedence chain, and its `match`/`matchesFilter` behave per the §5 correctness bar (payloads validate under the draft-07 dialect both majors declare, so a `$ref`-sibling keyword is dialect-correctly not enforced, pinned by a tripwire test — D-018 supersedes D-005).
 
 #### ingestion/ branch-tip fetch and lockfile writer
 **UID**: R-005
@@ -294,6 +294,30 @@ A preflight verb running a fixed ordered list of named checks (runtime floor via
 **TEST**: test/readme-quickstart.test.ts, test/guides-cookbook.test.ts, test/cli-dispatch.test.ts
 Every error reachable on the clone→demo→init→wire→up→first-publish path names what failed plus one concrete next step (with a "(try `offbook doctor`)" suffix only where doctor genuinely diagnoses it), pinned by tests; the README quickstart and scenario-cookbook recipes are executable docs — the quickstart gate runs the canonical command sequence and asserts fence↔canonical equivalence, the cookbook gate loads every recipe against the bundled demo registry with zero diagnostics.
 
+#### AsyncAPI supported-version contract and preflight
+**UID**: R-037
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/model/spec-version.ts, src/registry/index.ts, src/ingestion/index.ts, src/cli/boot.ts
+**TEST**: src/model/spec-version.test.ts, src/registry/index.test.ts, src/ingestion/index.test.ts, test/gate-validation.test.ts, test/upstream-drift.test.ts
+`registry/` refuses any spec whose declared version it can read and has not tested (the set is 2.0.0-2.6.0, 3.0.0, 3.1.0) with a branded, actionable error naming the version, every tested version, and the convert remedy, checked parser-free before `parse()`; an unreadable or absent `asyncapi` field defers to the parser's own diagnostics rather than being guessed at as a version problem (D-019), and a drift test keeps the tested set aligned with what `@asyncapi/specs` exposes; the declared version is recorded as `spec-version` in `specs.lock` and on `SpecInfo`.
+
+#### AsyncAPI payload schema boundary
+**UID**: R-038
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/registry/index.ts
+**TEST**: src/registry/index.test.ts, test/gate-validation.test.ts
+`registry/` extracts the payload schema from the Multi Format Schema Object wrapper, validates under draft-07 with an explicit stamp, diagnoses post-draft-07 keywords it cannot honor, contains a compile failure as a violation rather than a crash or a green pass, and validates an operation's multiple messages as `anyOf`.
+
+#### MQTT binding integrity across spec majors
+**UID**: R-039
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/registry/index.ts, src/model/index.ts, src/compose/index.ts
+**TEST**: src/registry/index.test.ts, test/gate-validation.test.ts, test/upstream-drift.test.ts
+`registry/` guards binding-supplied `qos`/`retain` values (falling through the §2 precedence chain on a bad value), reports unknown keys against a hand-authored mqtt operation-binding key set that honors the schema's `x-` vendor-extension pattern and is drift-tested against `@asyncapi/specs` (a devDependency, never imported from `src/`; D-019), reports an mqtt CHANNEL binding as ignored, and reports MQTT-5-only binding fields as unhonored under the MQTT 3.1.1-only constraint.
+
 <!--
 Seeding is staged (doc-system.md §7). Batch 1 (R-001..R-007) + R-008 (M0) + R-009 (broker tier-1 residual): seeded; reconciled where traces exist (the R-006/R-007 spikes remain open). Batch 2+ (R-010..R-031): the full module/spike/gate carve per D-007 and docs/archive/intake/2026-07-21-batch-2-seeding-carve.md.
 What remains unseeded resolves case by case (not bulk):
diff --git a/bun.lock b/bun.lock
index d919bd0..0fc51db 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,7 +5,7 @@
     "": {
       "name": "offbook",
       "dependencies": {
-        "@asyncapi/parser": "^3.4.0",
+        "@asyncapi/parser": "^3.6.0",
         "aedes": "^0.51.3",
         "aedes-server-factory": "^0.2.1",
         "ajv": "^8.17.1",
@@ -16,6 +16,7 @@
         "yaml": "^2.5.0",
       },
       "devDependencies": {
+        "@asyncapi/specs": "^6.11.1",
         "@biomejs/biome": "^1.9.0",
         "@hughescr/stryker-bun-runner": "^1.3.8",
         "@stryker-mutator/core": "^9.6.1",
diff --git a/docs/guides/wiring-your-service.md b/docs/guides/wiring-your-service.md
index 067cac5..14f1d56 100644
--- a/docs/guides/wiring-your-service.md
+++ b/docs/guides/wiring-your-service.md
@@ -23,7 +23,20 @@ services:
 
 Multiple services merge into one mock: add one entry per service.
 
-## 2. environments.yaml (optional in v1)
+## 2. AsyncAPI versions
+
+offbook reads AsyncAPI **2.0.0 through 2.6.0, 3.0.0, and 3.1.0**. 3.1.0 is the recommended target for new specs. A 1.x spec is refused with a message telling you to convert it.
+
+### If your spec is 2.x, check its perspective
+
+AsyncAPI 2.x names operations from the point of view of your service's *counterparties*, which is the opposite of what most people assume:
+
+- `subscribe` means **your service publishes** the message, so offbook treats it as `toClient` and mocks it for your browser app to receive.
+- `publish` means **your service consumes** the message, so offbook treats it as `fromClient` and validates what your browser app sends.
+
+That is what the specification says, and it is what the official converter does. But the convention is widely misread, and some generators grew flags (`view=provider`, `inverseOperations=true`) for specs authored the other way around. If every mocked channel points the wrong way, your spec was probably written from the client's perspective. No tool can detect this from the document, so it needs a human read.
+
+## 3. environments.yaml (optional in v1)
 
 ```yaml
 environments:
@@ -33,7 +46,7 @@ environments:
 v1 records requested versions per environment but fetches branch tips; leave
 it scaffolded as-is unless you already know you need it.
 
-## 3. First `offbook up`
+## 4. First `offbook up`
 
 ```sh
 offbook up
@@ -49,14 +62,14 @@ further.
 A fetch failure aborts `up` (no half-booted mock). The error names the
 service; `offbook doctor` checks all repos' reachability in one pass.
 
-## 4. Keeping specs fresh
+## 5. Keeping specs fresh
 
 ```sh
 offbook specs          # provenance: what was fetched, when, which SHA
 offbook specs update   # re-resolve branch tips + hot-swap the running mock
 ```
 
-## 5. Make it answer: scenarios
+## 6. Make it answer: scenarios
 
 An ingested spec gives you topics, retained state, and validation. To make
 the mock *react* (ack commands, chain state changes), add L2 scenarios:
diff --git a/docs/specs/build-plan.md b/docs/specs/build-plan.md
index 997213c..48193fb 100644
--- a/docs/specs/build-plan.md
+++ b/docs/specs/build-plan.md
@@ -18,7 +18,7 @@
 | Lint / format | **Biome** | single fast tool |
 | Control-plane HTTP | **Hono** | tiny, typed routing, Bun-native |
 | Broker | **Aedes** | ws + tcp, MQTT 3.1.1 (§3) |
-| AsyncAPI | **`@asyncapi/parser`** (3.x) | parse + validate; dereferences `$ref` before validating (§5) |
+| AsyncAPI | **`@asyncapi/parser`** (`^3.6.0`) | parse + validate; dereferences `$ref` before validating (§5). Its `@asyncapi/specs` transitive is **also a devDependency**, used only by `test/upstream-drift.test.ts` to pin offbook's hand-authored version set and mqtt binding key set against the installed schemas; `src/` never imports it (D-019) |
 | Schema validation | **Ajv** 8 + `ajv-formats` | runtime payload validation |
 | Fake data | **`json-schema-faker@0.6.2`** | pinned exact; seeded via its **native `seed`** option (Mulberry32-based; no second PRNG wraps it — R4); Ajv-recheck before emit (§4) |
 | YAML | **`yaml`** | config + scenario + spec parsing |
diff --git a/docs/specs/contracts.md b/docs/specs/contracts.md
index 687a5da..03a8476 100644
--- a/docs/specs/contracts.md
+++ b/docs/specs/contracts.md
@@ -34,7 +34,7 @@ interface Channel {     // produced by the Spec Registry
   topic: string;        // address / pattern (may contain {params})
   direction: Direction; // normalized ONCE here (design §5): v3 send→toClient · receive→fromClient; v2 subscribe→toClient · publish→fromClient
   service: string;      // owning service (services.yaml key) — feeds ?service= filters + SpecInfo/TopicInfo (§5, §6)
-  schema: object;       // FULLY BUNDLED JSON Schema — every $ref inlined or rewritten to internal $defs, no dangling/external ref, 2020-12 dialect declared so Ajv compiles it standalone; feeds the L1 faker + GET /topics
+  schema: object;       // FULLY BUNDLED JSON Schema — every $ref inlined or rewritten to internal $defs, no dangling/external ref, draft-07 dialect declared (D-018) so Ajv compiles it standalone; feeds the L1 faker + GET /topics
   validate: (payload: unknown) => SchemaError[];  // compiled from `schema`
   qos?: 0 | 1 | 2;      // RESOLVED by the registry per the §2 precedence chain (G13)
   retain?: boolean;     // RESOLVED by the registry per the §2 precedence chain (G13)
@@ -46,13 +46,15 @@ interface SpecRegistry {  // the ONE concrete-topic → Channel matcher; lives i
   match(topic: string): { channel: Channel; params: Record<string, string> } | undefined;
   matchesFilter(filter: string, topic: string): boolean;  // MQTT +/# SUBSCRIBE-side filter test (F6); shared by engine (wildcard replay, §2) + scenarios (when.topic, §3a)
   channels(): readonly Channel[];
+  diagnostics(): readonly Diagnostic[];  // registry-time spec-QUALITY findings (D-018): discoverable only while BUILDING the catalog, so they cannot be recomputed from a Channel later (binding placement, dialect mismatch, a schema that would not compile). Collected once at build; the composition root merges them into GET /v1/diagnostics (§5) beside the computed ones. Reuses the closed `spec-load` kind with a machine-greppable `detail` tag prefix; `mergeRegistries` concatenates its inputs'
 }
 ```
 
 - **One matcher, owned by `registry/`.** Every consumer that turns a concrete `NormalizedMessage.topic` into its `Channel` — `/publish` direction inference, `unknown-topic`/`schema` validation, `Violation.channel` stamping, the `onSubscribe` initial-state path, L3 `register` routing (§3) — imports this single `match`. Hand-rolling a second matcher is forbidden **for concrete-topic→`Channel` resolution** (divergent semantics make the CI gate non-deterministic). **`match` and `matchesFilter` delegate to [`mqtt-pattern`](https://www.npmjs.com/package/mqtt-pattern)**, minding the syntax gap: mqtt-pattern's named capture is `+param`/`#param`, **not** AsyncAPI's `{param}` (a `{param}` segment is matched *literally*). So `match` **rewrites each single-segment `{p}` on the channel address to mqtt-pattern's `+p`**, then calls `exec` on the rewritten pattern; because the rewrite is `{p}`→`+p`, the returned captures are already keyed by `p` (the back-map is the identity — no rename layer). `matchesFilter` calls `matches` directly on a native MQTT `+`/`#` SUBSCRIBE filter and needs **no** rewrite (R2). One tested library, no hand-rolled segment-splitting — while offbook's precedence (below) stays our sort on top, operating on the original `{param}` form. A build-time parity spike confirms the `{p}`→`+p` rewrite reproduces AsyncAPI single-segment capture exactly (it does **not** assert mqtt-pattern reads `{param}` natively — it does not) before we rely on it. *(The L2 scenario `when.topic` matcher — which fuses `{param}` capture, `+`/`#` filter, and `payloadMatch` in one walk, l2 §4 — is a separate, **permitted** matcher: a different operation `match` deliberately refuses — it never interprets `+`/`#` (see the *"Match is over the channel ADDRESS"* bullet below).)*
 - **Match is over the channel ADDRESS.** `{param}` is a **single-segment** AsyncAPI capture on the channel address (`state/{deviceId}` ↦ `{ deviceId: 'thermostat-1' }`). MQTT `+`/`#` are **SUBSCRIBE-side filters** (a different operation, tested by `matchesFilter` above per the design §7a wildcard policy) — they are **not** channel patterns and `match` never interprets them.
 - **Precedence when more than one channel matches:** most-specific first — a literal segment beats a `{param}` segment at the same position — then declaration order in the spec. Two channels matching the same concrete topic resolve to the same winner on every run.
-- **`Channel.schema` is fully bundled** so it is hand-able to Ajv and the L1 faker with no parser/registry present: the `external-ref.yaml` + `shared/common.yaml` fixture (the design §5/§12.4 bundling bar) must, taken as `channel.schema` alone, compile under Ajv standalone. The bundling comes from the **parser stack** — `@asyncapi/parser`'s resolved output (it depends on `@apidevtools/json-schema-ref-parser`, whose `$RefParser.bundle()` produces the self-contained internal-`$ref` form, dedup'd not blown-up) — **not** hand-rolled `$ref`-walking in `registry/`; we only stamp `$schema: 2020-12` (R1).
+- **`Channel.schema` is fully bundled** so it is hand-able to Ajv and the L1 faker with no parser/registry present: the `external-ref.yaml` + `shared/common.yaml` fixture (the design §5/§12.4 bundling bar) must, taken as `channel.schema` alone, compile under Ajv standalone. The bundling comes from the **parser stack** — `@asyncapi/parser`'s resolved output (it depends on `@apidevtools/json-schema-ref-parser`, whose `$RefParser.bundle()` produces the self-contained internal-`$ref` form, dedup'd not blown-up) — **not** hand-rolled `$ref`-walking in `registry/`; we only stamp the dialect (R1).
+- **`Channel.schema` is validated under JSON Schema draft-07**, the dialect both AsyncAPI majors declare for the Schema Object ("a superset of JSON Schema Draft 07") and the one `@asyncapi/parser` actually emits; `registry/` stamps `$schema: http://json-schema.org/draft-07/schema#` explicitly, so the schema `GET /topics` hands out is self-describing (D-018). Stamping 2020-12 over a draft-07 schema was the root cause of a legal tuple payload (`items` as an array) crashing `ajv.compile()` and of `additionalItems` being silently ignored. Keywords JSON Schema added after draft-07 (`prefixItems`, `unevaluatedProperties`, `dependentRequired`, and friends) therefore cannot be honored, and are surfaced as a `spec-load` diagnostic rather than ignored in silence.
 
 - **Direction is derived, not stored on messages:** flow position (`onInbound` vs `emit`) gives inbound/outbound; the topic→`Channel` lookup gives the spec-declared direction. In v1 it's a clean bijection (the client only publishes `fromClient`; the mock only emits `toClient`).
 - **`delayMs`** is resolved in the engine (seeded Mulberry32 draw — see §3 Behavior engine) and consumed by the engine scheduler; the broker ignores it.
@@ -283,7 +285,7 @@ interface Violation {
 interface TopicInfo { topic: string; direction: Direction; service: string;
   title?: string; description?: string; schema: object; example?: unknown; qos?: 0|1|2; retain?: boolean; }
 interface StateEntry { topic: string; payload: unknown; qos?: 0|1|2; retain: true; }  // retain is always true — clearing a retained topic EVICTS it (§2), so /state never returns tombstones; a decode-failure (§2) is never stored, so payload is always a successfully-decoded value
-interface SpecInfo { service: string; declaredVersion?: string; source: string; contentHash: string; channelCount: number; fetchedAt: string; }  // declaredVersion = info.version, read parser-free by ingestion/ (shallow yaml read, G12) — NOT the requested version (they differ in v1 branch mode). fetchedAt (ISO8601, propagated from the lockfile `fetched-at`) = spec provenance/age for TRUST CALIBRATION — the tool validates against the spec AS FETCHED, never the live service; surfaced NEUTRALLY (no stale threshold) by GET /specs + status (design §7, Mode 3)
+interface SpecInfo { service: string; declaredVersion?: string; specVersion?: string; source: string; contentHash: string; channelCount: number; fetchedAt: string; }  // declaredVersion = info.version, read parser-free by ingestion/ (shallow yaml read, G12) — NOT the requested version (they differ in v1 branch mode). specVersion = the AsyncAPI DOCUMENT version (the `asyncapi` field, e.g. '3.1.0'), read in the same parser-free pass — which spec major this service is on (D-018), not the service's own info.version. fetchedAt (ISO8601, propagated from the lockfile `fetched-at`) = spec provenance/age for TRUST CALIBRATION — the tool validates against the spec AS FETCHED, never the live service; surfaced NEUTRALLY (no stale threshold) by GET /specs + status (design §7, Mode 3)
 interface ScenarioInfo { name: string; when?: string; stepCount: number; source: string; }  // GET /scenarios discovery (P8): `when` = the reactive trigger topic (absent ⇒ on-demand/trigger-only); source = scenario file path
 interface Diagnostic { kind: 'scenario-load' | 'overlap' | 'spec-load' | 'uninstantiated';
   severity: 'error' | 'warning' | 'info'; detail: string; source?: string; scenarioName?: string; }
@@ -298,6 +300,12 @@ interface Diagnostic { kind: 'scenario-load' | 'overlap' | 'spec-load' | 'uninst
 //   ADDRESS goes in `source?`; teaching `detail` ("validates green but its schema constrains nothing — passing here is
 //   unverified"). Scoped tight to the unambiguous vacuous shapes — NOT a graded quality score (deferred). FATAL load
 //   failures (unreachable/unparseable spec) do NOT appear here — they abort `up` in the foreground (design §7 Mode 1).
+//   'spec-load' ALSO carries the REGISTRY-TIME findings of `SpecRegistry.diagnostics()` (§1, D-018): findings only the
+//   catalog build can see, so they cannot be recomputed from a Channel. The kind union stays closed (four values, and
+//   DiagnosticSummary.byKind keeps exactly those four keys, zero-filled); each finding is instead machine-identified by
+//   a stable tag prefix on `detail` (the tag, then `: `, then the sentence): 'binding-on-channel',
+//   'binding-invalid-value', 'binding-unknown-key', 'mqtt5-field-ignored', 'dialect-mismatch', 'schema-compile-failed'.
+//   Channel ADDRESS in `source?` as above, so filtering by tag and by address both work.
 
 interface ValidationSummary {    // the CI-facing payload of GET /v1/validation
   errors: number;                // count of severity === 'error' violations (within the retained window)
@@ -365,6 +373,7 @@ interface ResolvedSpec {
   resolvedSha: string;      // FULL canonical commit sha (40 hex sha-1 / 64 hex sha-256) — the pin, never abbreviated
   source: string;           // human origin, e.g. "dev@org/service-b:asyncapi.yaml"
   declaredVersion?: string; // info.version — shallow parser-free read by ingestion/ (G12), not the registry parse; best-effort (absent ⇒ undefined)
+  specVersion?: string;     // the `asyncapi` document version (e.g. '3.1.0') — same parser-free pass; best-effort (absent ⇒ undefined)
   fetchedAt: string;        // ISO8601
 }
 
@@ -421,6 +430,7 @@ interface LockEntry {
   resolvedSha: string;                 // FULL canonical commit sha — never abbreviated
   specPath: string;
   declaredVersion?: string;        // info.version
+  specVersion?: string;            // the `asyncapi` document version
   contentHash: string;                 // "sha256:…"
   fetchedAt: string;                   // ISO8601
   resolvedVersion?: string;            // v2 only — semver after range policy
@@ -439,6 +449,7 @@ services:
     resolved-sha: 9f2c3a1b4d5e6f70819a2b3c4d5e6f7081929a3b   # FULL commit sha
     spec-path: asyncapi.yaml
     declared-version: 2.0.0    # info.version
+    spec-version: 3.1.0             # the `asyncapi` document version (optional, best-effort)
     content-hash: sha256:c1d2…      # byte fingerprint
     fetched-at: 2026-06-23T…
     # resolved-version:  (v2 only — semver after range policy)
@@ -448,6 +459,7 @@ services:
 
 - Recording **`resolved-ref` + full `resolved-sha` + `content-hash`** in v1 lays the **data** for reproducibility; the **guarantee itself is realized in v2** by the `up --frozen` reader (§6 GitRefResolver bullet) — rebuild the exact mock even after the branch moves by re-resolving each service at its `resolved-sha`. v1 *writes* the SHA but never reads it back; the byte-identical acceptance test is a **v2** check against a **pinned SHA**, not a live tip (a mutable tip has no operationally-definable byte-identity).
 - **`declared-version` is written by `ingestion/`, parser-free (G12).** Ingestion does a **shallow `info.version` read with the `yaml` lib** (already a dependency) on the fetched bytes — **no `@asyncapi/parser` import** — so the lockfile `declared-version` and `SpecInfo.declaredVersion` are populated without serializing ingestion behind `registry/`'s full parse. It is best-effort: absent `info.version` ⇒ the field stays `undefined` (optional on both `ResolvedSpec` and `LockEntry`).
+- **`spec-version` rides the same parser-free pass (D-018).** Alongside `info.version`, ingestion reads the document's **`asyncapi`** field and records it as `spec-version` in the lockfile and `SpecInfo.specVersion`, so `GET /v1/specs` answers which spec major each service is on. It is **not** `requested-version` and **not** `declared-version`: those are the service's own release version, this is the AsyncAPI document version (`2.0.0`…`3.1.0`, the supported range). Optional and best-effort on the same terms: an unreadable or absent `asyncapi` field leaves it `undefined` and the key is omitted from the YAML. `offbook doctor` deliberately does **not** report it: doctor's spec checks are network-free, while the spec text lives in a remote repo that only `ingestion/` fetches.
 - The declared-vs-requested **drift-check is v2** (v1 always fetches a branch tip, so there's no resolved semver to check).
 - **Seam-complete:** `environments.yaml` exists in v1 so `requested-version` is real and the requested-vs-resolved gap is *honestly visible*; v2 swaps `StaticManifestSource → ReleaseToolingSource` with no restructure. *(F20: kept deliberately — the honest requested-vs-resolved provenance is judged worth the v1 carry, over deferring the unused machinery to v2.)*
 
diff --git a/docs/superpowers/plans/2026-07-30-asyncapi-version-support.md b/docs/superpowers/plans/2026-07-30-asyncapi-version-support.md
new file mode 100644
index 0000000..1f36e9e
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-30-asyncapi-version-support.md
@@ -0,0 +1,1993 @@
+# AsyncAPI 2.0.0 through 3.1.0 Support Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Declare and test the AsyncAPI 2.0.0-through-3.1.0 support range, and fix the three ingestion defects in the path that serves it, so no supported spec version can silently validate green against nothing.
+
+**Architecture:** All behavioral change lands in `src/registry/index.ts`, the single place parser output becomes a `Channel`. A new tier-0 helper (`src/model/spec-version.ts`) provides the parser-free version read used both by the registry preflight gate and by `ingestion/` for lockfile provenance. Registry-time findings reach `GET /v1/diagnostics` through a new `SpecRegistry.diagnostics()` member merged by the composition root, following the existing pattern where `src/compose/index.ts` assembles diagnostics from several sources.
+
+**Tech Stack:** TypeScript on Bun 1.3.14, `@asyncapi/parser` 3.6.0, `@asyncapi/specs` 6.11.1, `ajv` 8.x (draft-07 build after Task 3), `ajv-formats`, `yaml`, Biome for lint, `bun test` for tests.
+
+**Spec:** `docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md`
+
+## Global Constraints
+
+Every task's requirements implicitly include these.
+
+- **Parser floor is `^3.6.0` exactly.** AsyncAPI 3.1.0 support landed in that release. Parser 3.4.0 and 3.5.0 resolve a specs package containing the 3.1.0 schema, pass their own dynamic version gate, then fail inside the Spectral ruleset with `AggregateError: Error running Nimma`.
+- **Supported spec versions, verbatim:** `2.0.0`, `2.1.0`, `2.2.0`, `2.3.0`, `2.4.0`, `2.5.0`, `2.6.0`, `3.0.0`, `3.1.0`.
+- **Payload validation dialect after Task 3 is JSON Schema draft-07**, stamped explicitly as `http://json-schema.org/draft-07/schema#`. Never 2020-12.
+- **Only `src/broker/` may import `aedes` or any MQTT/transport package.** Lint-enforced. Nothing in this plan needs it.
+- **Import style (D-013):** upward reaches use `#src/…`; same-directory and downward stay relative with explicit `.ts` extensions. Enforced by `test/import-style.test.ts`.
+- **No hand-rolled schema interpretation (R1).** Use `@asyncapi/parser` and Ajv. Reading `properties` keys off an official binding schema is allowed; walking or rewriting adopter schemas is not.
+- **Verify by exit code, never by printed pass/fail counts.** `bun test <single-file>` may exit 1 with zero failures because the per-file coverage floor judges partially-imported files. Gate on full `bun test`. Coverage floors are per-file: `lines = 0.74`, `functions = 0.64`.
+- **`bun scripts/check-docs.ts` must exit 0 at every commit.** Requirement ids must stay unique and contiguous; a `tested` requirement needs a `TEST` trace whose files carry matching arrow tags (`// [utest->R-###]`, or `itest`/`stest`), verified in both directions.
+- **Commit messages carry no `Co-Authored-By` and no AI-attribution trailer.**
+- **Prose in docs and comments avoids em-dashes.** Use commas, colons, parentheses, or separate sentences.
+- **Touching `fixtures/asyncapi/` couples to the R-027 spike tripwire.** `test/spikes/jsf-fidelity.test.ts` asserts that `SPIKE_FIXTURES` (in `scripts/spike-jsf-fidelity.ts`) covers the `fixtures/asyncapi/*.yaml` listing *exactly*, and its `EXPECTED` map pins draws (channels x 10 seeds) and failures per fixture. So **adding a fixture, or adding a channel to an existing one, makes the full suite red until you update both.** Do the maintenance the tripwire itself prescribes: register the fixture, re-measure, and note the re-measurement citing D-018. Never exempt a fixture from the listing assertion and never relax `failures: 0` to accommodate a draw. Discovered in Task 2, which had to register `multi-format.yaml`; it recurs in Task 3 (a new `composition.yaml` channel) and Task 8 (`v2-oldest.yaml`).
+
+## Deviations from the spec (read before starting)
+
+Two things were discovered while planning that the spec got wrong. Both are deliberate, and both are narrower than what the spec described.
+
+1. **Diagnostics reuse the existing `kind: "spec-load"` rather than adding six new kinds.** The spec listed `schema-compile-failed`, `binding-invalid-value`, `binding-unknown-key`, `binding-on-channel`, `mqtt5-field-ignored`, and `dialect-mismatch` as new `/v1/diagnostics` entries. `Diagnostic.kind` is a closed four-value union and `DiagnosticSummary.byKind` requires all keys present and zero-filled, so six new kinds would churn the model, `src/control-plane/index.ts`, its tests, and the canonical `contracts.md` §5 tables. `spec-load` is already documented as "non-fatal spec-QUALITY findings surfaced at load", which is exactly what these are. The six names survive as a stable machine-greppable prefix on `detail` (for example `dialect-mismatch: '<topic>' uses …`).
+2. **`offbook doctor` does not report `spec-version`.** The spec said it would. It cannot: `doctor`'s spec check is deliberately network-free and shape-only, while the spec text lives in a remote repo that only `ingestion/` fetches. The version is recorded in `specs.lock` and exposed on `SpecInfo` via `GET /v1/specs`, which is where an adopter can actually see it.
+
+## File Structure
+
+**Created**
+
+- `src/model/spec-version.ts` — tier-0 pure functions: `readSpecVersion` (parser-free `asyncapi` field read) and the `SUPPORTED_SPEC_VERSIONS` contract plus `isSupportedSpecVersion`. Lives in `model/` so `registry/` and `ingestion/`, which are tier-1 peers, can both use it without cross-importing.
+- `src/model/spec-version.test.ts` — unit tests for the above.
+- `fixtures/asyncapi/multi-format.yaml` — AsyncAPI 3.1.0, explicit `{schemaFormat, schema}` payload on both a `send` and a `receive` operation.
+- `fixtures/asyncapi/v2-oldest.yaml` — AsyncAPI 2.0.0, `subscribe` plus `publish`, MQTT operation binding at `qos: 2`.
+
+**Modified**
+
+- `src/registry/index.ts` — all behavioral change: preflight gate, payload extraction, dialect, diagnostics collection, compile containment, multi-message `anyOf`, binding integrity.
+- `src/registry/index.test.ts` — tests for each of the above.
+- `src/model/index.ts` — `SpecRegistry.diagnostics()`; `specVersion` on `ResolvedSpec`, `LockEntry`, `SpecInfo`.
+- `src/compose/index.ts:183-190` — merge `registry.diagnostics()` into the diagnostics list.
+- `src/ingestion/index.ts` — read and record `specVersion`; serialize `spec-version`.
+- `src/cli/boot.ts` — carry `specVersion` into `SpecInfo`.
+- `fixtures/asyncapi/composition.yaml` — add a tuple-form array payload.
+- `fixtures/asyncapi/external-ref.yaml` — reword the D-005 sibling comment.
+- `fixtures/asyncapi/README.md` — two new rows, supported-version statement.
+- `docs/specs/contracts.md` — dialect reversal in §5, `SpecRegistry.diagnostics()`, `spec-version` on the lockfile and `SpecInfo`.
+- `DECISIONS.md` — add `D-018`, add a superseded note to `D-005`.
+- `REQUIREMENTS.md` — add `R-037`, `R-038`, `R-039`.
+- `README.md`, `docs/guides/wiring-your-service.md` — supported range, 3.1.0 recommendation, v2 perspective caveat.
+- `package.json` — parser floor.
+- `test/gate-validation.test.ts` — extend R-028 over the new fixtures. **Confirm the filename first** with `ls test/`; the R-028 trace in `REQUIREMENTS.md` is authoritative.
+
+---
+
+### Task 1: Supported-version contract and preflight gate
+
+Establishes the version promise, the parser floor, and the doc ids every later task references. The doc stubs are folded in here so `check-docs` stays green from the first commit and later tasks can add arrow tags against real requirement ids.
+
+**Files:**
+- Create: `src/model/spec-version.ts`, `src/model/spec-version.test.ts`
+- Modify: `src/registry/index.ts` (preflight gate before `parser.parse`), `package.json` (parser floor), `REQUIREMENTS.md` (add R-037, R-038, R-039), `DECISIONS.md` (add D-018)
+- Test: `src/model/spec-version.test.ts`, `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: nothing from earlier tasks.
+- Produces: `SUPPORTED_SPEC_VERSIONS: readonly string[]`, `readSpecVersion(specText: string): string | undefined`, `isSupportedSpecVersion(v: string | undefined): boolean`, all exported from `src/model/spec-version.ts`. `buildRegistry` throws `Error` with a message beginning `unsupported AsyncAPI version` for any version outside the set.
+
+- [ ] **Step 1: Write the failing test for the version helper**
+
+Create `src/model/spec-version.test.ts`:
+
+```ts
+// [utest->R-037]
+import { expect, test } from "bun:test";
+// same directory as its subject, so relative per D-013 (NOT the #src/ alias)
+import {
+	SUPPORTED_SPEC_VERSIONS,
+	isSupportedSpecVersion,
+	readSpecVersion,
+} from "./spec-version.ts";
+
+test("reads the asyncapi version from spec text without a parser", () => {
+	expect(readSpecVersion("asyncapi: 3.0.0\ninfo: { title: T, version: 1.0.0 }")).toBe("3.0.0");
+	expect(readSpecVersion("asyncapi: '2.6.0'\ninfo: { title: T, version: 1.0.0 }")).toBe("2.6.0");
+});
+
+test("a YAML-numeric version is normalized to a string", () => {
+	// `asyncapi: 2.6` is a YAML float, not a string; String() keeps the read honest
+	expect(readSpecVersion("asyncapi: 2.6")).toBe("2.6");
+});
+
+test("absent or unparseable spec text yields undefined, never a throw", () => {
+	expect(readSpecVersion("info: { title: T }")).toBeUndefined();
+	expect(readSpecVersion("this: [is: not: valid: yaml")).toBeUndefined();
+	expect(readSpecVersion("")).toBeUndefined();
+});
+
+test("the supported set is exactly the tested promise (2.0.0-2.6.0, 3.0.0, 3.1.0)", () => {
+	expect([...SUPPORTED_SPEC_VERSIONS]).toEqual([
+		"2.0.0",
+		"2.1.0",
+		"2.2.0",
+		"2.3.0",
+		"2.4.0",
+		"2.5.0",
+		"2.6.0",
+		"3.0.0",
+		"3.1.0",
+	]);
+});
+
+test("1.x, the 2.0.0 release candidates, and absent versions are unsupported", () => {
+	expect(isSupportedSpecVersion("3.1.0")).toBe(true);
+	expect(isSupportedSpecVersion("2.0.0")).toBe(true);
+	expect(isSupportedSpecVersion("1.2.0")).toBe(false);
+	expect(isSupportedSpecVersion("2.0.0-rc1")).toBe(false);
+	expect(isSupportedSpecVersion("4.0.0")).toBe(false);
+	expect(isSupportedSpecVersion(undefined)).toBe(false);
+});
+```
+
+- [ ] **Step 2: Run it to make sure it fails**
+
+Run: `bun test src/model/spec-version.test.ts`
+Expected: FAIL, module `#src/model/spec-version.ts` cannot be resolved. (Ignore any exit-1-with-zero-failures noise from the per-file coverage floor on focused runs; here the failure is a real resolution error.)
+
+- [ ] **Step 3: Implement the helper**
+
+Create `src/model/spec-version.ts`:
+
+```ts
+// R-037 — the AsyncAPI version contract plus a parser-free shallow read of the
+// `asyncapi` field. Tier 0 (model): pure functions over raw text, so both
+// `registry/` (the preflight gate) and `ingestion/` (lockfile provenance, G12)
+// can use them without a cross-import between tier-1 peers.
+import { parse as parseYaml } from "yaml";
+
+// The versions offbook PROMISES and TESTS. Deliberately an explicit list rather
+// than `Object.keys(specs.schemas)`: the parser derives its accepted set from
+// whatever @asyncapi/specs resolves at install time, so a schema being present
+// does NOT mean the parser's ruleset handles that version. Parser 3.4.0 and
+// 3.5.0 accept a 3.1.0 document past their version gate and then die inside
+// Spectral with "Error running Nimma". See D-018.
+export const SUPPORTED_SPEC_VERSIONS = [
+	"2.0.0",
+	"2.1.0",
+	"2.2.0",
+	"2.3.0",
+	"2.4.0",
+	"2.5.0",
+	"2.6.0",
+	"3.0.0",
+	"3.1.0",
+] as const;
+
+// Best-effort, mirroring ingestion's readDeclaredVersion (G12): no
+// @asyncapi/parser, no schema interpretation. A spec that will not yaml-parse,
+// or that has no `asyncapi` field, just yields undefined.
+export function readSpecVersion(specText: string): string | undefined {
+	try {
+		const doc = parseYaml(specText) as { asyncapi?: unknown } | null;
+		const v = doc?.asyncapi;
+		return v === undefined || v === null ? undefined : String(v);
+	} catch {
+		return undefined;
+	}
+}
+
+export function isSupportedSpecVersion(v: string | undefined): boolean {
+	return (
+		v !== undefined && (SUPPORTED_SPEC_VERSIONS as readonly string[]).includes(v)
+	);
+}
+```
+
+- [ ] **Step 4: Run the helper test to verify it passes**
+
+Run: `bun test src/model/spec-version.test.ts`
+Expected: all 5 tests pass. Exit code may still be 1 on a focused run because of the per-file coverage floor; trust the printed failure count of 0 here, per the bunfig note.
+
+- [ ] **Step 5: Write the failing test for the registry preflight gate**
+
+Append to `src/registry/index.test.ts`. Match the file's existing import block and helper style; if it already has a `registryFor` helper, reuse it rather than redefining one.
+
+```ts
+// [utest->R-037]
+test("refuses a 1.x spec with an actionable, branded error", async () => {
+	const spec = `asyncapi: '1.2.0'
+info: { title: Legacy, version: 1.0.0 }
+topics:
+  t.one:
+    publish:
+      payload: { type: object }
+`;
+	const attempt = buildRegistry({
+		specText: spec,
+		service: "legacy",
+		config: DEFAULT_CONFIG,
+	});
+	await expect(attempt).rejects.toThrow(/unsupported AsyncAPI version "1\.2\.0"/);
+	// names the supported range and the remedy, not just the problem
+	await expect(attempt).rejects.toThrow(/2\.0\.0/);
+	await expect(attempt).rejects.toThrow(/asyncapi convert/);
+});
+
+// [utest->R-037]
+test("refuses a spec with no asyncapi field", async () => {
+	await expect(
+		buildRegistry({
+			specText: "info: { title: T, version: 1.0.0 }",
+			service: "nover",
+			config: DEFAULT_CONFIG,
+		}),
+	).rejects.toThrow(/unsupported AsyncAPI version/);
+});
+
+// [utest->R-037]
+test("accepts every version in the supported contract", async () => {
+	for (const v of SUPPORTED_SPEC_VERSIONS) {
+		const spec = v.startsWith("3.")
+			? `asyncapi: ${v}
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/one, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`
+			: `asyncapi: ${v}
+info: { title: T, version: 1.0.0 }
+channels:
+  t/one:
+    subscribe:
+      operationId: s
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+		const reg = await buildRegistry({
+			specText: spec,
+			service: "s",
+			config: DEFAULT_CONFIG,
+		});
+		expect(reg.channels().length, `version ${v} should yield one channel`).toBe(1);
+	}
+});
+```
+
+Add `SUPPORTED_SPEC_VERSIONS` to the test file's imports. This one is a genuine upward reach from `src/registry/`, so the alias is correct here:
+
+```ts
+import { SUPPORTED_SPEC_VERSIONS } from "#src/model/spec-version.ts";
+```
+
+Note the contrast with Step 1: `src/model/spec-version.test.ts` sits in the same directory as its subject, so it imports `./spec-version.ts` relatively, per D-013. Apply the rule from `CLAUDE.md`, not the shape of a neighbouring import.
+
+- [ ] **Step 6: Run it to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: the three new tests FAIL. The 1.x case currently rejects with `failed to parse spec: Version "1.2.0" is not supported…` from the parser, which does not match `/unsupported AsyncAPI version/`, and the no-version case does not reject at all.
+
+- [ ] **Step 7: Add the preflight gate to the registry**
+
+In `src/registry/index.ts`, add the import beside the existing model import:
+
+```ts
+import {
+	SUPPORTED_SPEC_VERSIONS,
+	isSupportedSpecVersion,
+	readSpecVersion,
+} from "#src/model/spec-version.ts";
+```
+
+Then insert the gate as the first statement inside `buildRegistry`, before the `parser.parse` calls:
+
+```ts
+	// R-037 preflight: check the declared version BEFORE handing the document to
+	// the parser. The parser's own gate is derived from @asyncapi/specs at
+	// install time, so an unsupported-but-present version can pass it and then
+	// fail deep in the Spectral ruleset with an opaque "Error running Nimma".
+	// Offbook's supported set is a promise it tests, so it is checked here (D-018).
+	const specVersion = readSpecVersion(opts.specText);
+	if (!isSupportedSpecVersion(specVersion)) {
+		throw new Error(
+			`unsupported AsyncAPI version ${
+				specVersion === undefined ? "(no `asyncapi` field found)" : `"${specVersion}"`
+			} in service '${opts.service}': offbook supports ${SUPPORTED_SPEC_VERSIONS[0]} through ${
+				SUPPORTED_SPEC_VERSIONS[SUPPORTED_SPEC_VERSIONS.length - 1]
+			}. Convert the spec first: \`asyncapi convert <file> --target-version 3.1.0\``,
+		);
+	}
+```
+
+- [ ] **Step 8: Run the registry test to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+- [ ] **Step 9: Raise the parser floor**
+
+Edit `package.json`, changing the dependency line to:
+
+```json
+    "@asyncapi/parser": "^3.6.0",
+```
+
+Run: `bun install`
+Expected: exit 0. The installed version is already 3.6.0, so `bun.lock` may be unchanged; that is fine.
+
+- [ ] **Step 10: Add the requirement and decision records**
+
+Append three requirements to `REQUIREMENTS.md`, following the exact field order used by existing entries (`UID`, `STATUS`, `COVERS`, `IMPL`, `TEST`, then the prose line). They start as `specified`, which needs no trace, and Task 10 flips them to `tested`.
+
+```markdown
+#### AsyncAPI supported-version contract and preflight
+**UID**: R-037
+**STATUS**: specified
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+`registry/` refuses any spec outside the tested support set (2.0.0-2.6.0, 3.0.0, 3.1.0) with a branded, actionable error naming the version, the range, and the convert remedy, checked parser-free before `parse()`; the declared version is recorded as `spec-version` in `specs.lock` and on `SpecInfo`.
+
+#### AsyncAPI payload schema boundary
+**UID**: R-038
+**STATUS**: specified
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+`registry/` extracts the payload schema from the Multi Format Schema Object wrapper, validates under draft-07 with an explicit stamp, diagnoses post-draft-07 keywords it cannot honor, contains a compile failure as a violation rather than a crash or a green pass, and validates an operation's multiple messages as `anyOf`.
+
+#### MQTT binding integrity across spec majors
+**UID**: R-039
+**STATUS**: specified
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+`registry/` guards binding-supplied `qos`/`retain` values (falling through the §2 precedence chain on a bad value), reports unknown keys against the official mqtt operation-binding key set, reports an mqtt CHANNEL binding as ignored, and reports MQTT-5-only binding fields as unhonored under the MQTT 3.1.1-only constraint.
+```
+
+Append `D-018` to `DECISIONS.md`, matching the field order of `D-017` (`Date`, `What`, `Why`, `Mitigations / notes`, `Obligations`, `From`, `Folds into`; copy the exact heading and field style from an existing entry):
+
+```markdown
+### D-018: offbook supports AsyncAPI 2.0.0-3.1.0, validates payloads under draft-07, and polices bindings itself
+**Date**: 2026-07-30
+**What**: Declare a tested support matrix (2.0.0-2.6.0, 3.0.0, 3.1.0; 1.x refused), raise the `@asyncapi/parser` floor to `^3.6.0`, gate the version in `registry/` before `parse()`, and harden the shared ingestion path: unwrap the Multi Format Schema Object payload wrapper, validate under JSON Schema draft-07 with an explicit stamp instead of stamping 2020-12, diagnose post-draft-07 keywords, contain Ajv compile failures, validate multi-message operations as `anyOf`, and police mqtt binding values and keys against the official binding schema's key set. Supersedes D-005's deferred 2020-12 obligation.
+**Why**: Three defects were found by research, none by a failing test. A valid 3.x multi-format payload made the channel validator accept everything including `null`, because `BaseModel.json()` returns the wrapper verbatim; that is the false-negative class R-028 exists to prevent. A legal draft-07 tuple schema crashed `bootProject` uncaught, because offbook stamped 2020-12 over a schema the parser emits as draft-07. 2.x maps `mqtt` to an empty schema, so `qos: 9` reached a `Channel` typed `0 | 1 | 2`. Converting 2.x to 3.x on ingest was considered and rejected: the fleet is mostly 3.x, so it would add a dependency and a lossy translation layer to serve a shrinking minority, and it would anchor diagnostics to a document the adopter never wrote. Draft-07 is the dialect BOTH majors declare and the parser actually emits, so validating under it is the root-cause fix and needs no schema rewriting (R1 intact).
+**Mitigations / notes**: Draft-07 silently ignores post-draft-07 keywords, so a dialect-mismatch diagnostic makes that loud. The explicit supported-version list is cross-checked by a test, because deriving it from `@asyncapi/specs` reproduces the trap that fooled parser 3.4.0/3.5.0. New findings reuse the existing closed `spec-load` diagnostic kind with a machine-greppable `detail` prefix rather than expanding the `Diagnostic.kind` union. A 2.x spec authored from the client's perspective still loads inverted and no tool can detect that; it is documented for adopters.
+**Obligations**: none deferred.
+**From**: brainstorm dialog 2026-07-30 after a deep-research pass; every behavioral claim verified empirically against the installed toolchain (results tabulated in the design doc).
+**Folds into**: src/model/spec-version.ts, src/registry/index.ts, src/ingestion/index.ts, docs/specs/contracts.md §5/§6, fixtures/asyncapi/, REQUIREMENTS.md (R-037-R-039), DECISIONS.md (D-005 superseded note)
+```
+
+- [ ] **Step 11: Verify the doc gate and the full suite**
+
+Run: `bun scripts/check-docs.ts; echo "EXIT=$?"`
+Expected: `EXIT=0`, and the printed count rises to 39 requirements and 18 decisions.
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+Run: `bun run lint && bun run typecheck; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+- [ ] **Step 12: Commit**
+
+```bash
+git add src/model/spec-version.ts src/model/spec-version.test.ts src/registry/index.ts src/registry/index.test.ts package.json bun.lock REQUIREMENTS.md DECISIONS.md
+git commit -m "feat(registry): gate the AsyncAPI supported-version contract (R-037)
+
+Refuse any spec outside the tested set (2.0.0-2.6.0, 3.0.0, 3.1.0) with a
+branded error naming the version, the range, and the convert remedy, checked
+parser-free before parse(). Raise the parser floor to ^3.6.0: 3.4.0/3.5.0 pass
+their own dynamic version gate on a 3.1.0 doc and then fail inside Spectral.
+
+Records D-018 and R-037..R-039."
+```
+
+---
+
+### Task 2: Unwrap the Multi Format Schema Object payload
+
+The highest-value fix. Today a valid AsyncAPI 3.x document using the explicit `{schemaFormat, schema}` payload form produces a channel that accepts everything, silently.
+
+**Files:**
+- Create: `fixtures/asyncapi/multi-format.yaml`
+- Modify: `src/registry/index.ts`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: the Task 1 preflight gate (the new fixture declares `3.1.0`, which the gate must already allow).
+- Produces: `extractPayloadSchema(payloadJson: unknown): object`, module-private in `src/registry/index.ts`. Tasks 3 and 7 call it.
+
+- [ ] **Step 1: Create the fixture**
+
+Create `fixtures/asyncapi/multi-format.yaml`. The strict schema (`required` plus `additionalProperties: false`) is what makes the regression assertion meaningful, and putting the hard case on both a `send` and a `receive` operation satisfies quality-bar item 3 (full-path coverage).
+
+```yaml
+asyncapi: 3.1.0
+info:
+  title: Multi Format Payloads
+  version: 1.0.0
+  description: >-
+    Payloads authored as the explicit Multi Format Schema Object
+    (`{schemaFormat, schema}`), which AsyncAPI 3.x permits for the DEFAULT
+    JSON-Schema format, not just for Avro or Protobuf. The parser returns that
+    wrapper verbatim from `payload().json()`, so a consumer that spreads it gets
+    a schema with no validation keywords: a validator that accepts everything
+    (D-018). Both directions carry the form, so the client-publish path is
+    covered too. Also the newest-supported-major acceptance fixture.
+servers:
+  mosquitto:
+    host: localhost:1883
+    protocol: mqtt
+    protocolVersion: '3.1.1'
+channels:
+  reading:
+    address: reading/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Reading:
+        name: Reading
+        payload:
+          schemaFormat: 'application/vnd.aai.asyncapi;version=3.1.0'
+          schema:
+            type: object
+            required: [sensorId, celsius]
+            additionalProperties: false
+            properties:
+              sensorId:
+                type: string
+              celsius:
+                type: number
+  calibrate:
+    address: calibrate/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Calibrate:
+        name: Calibrate
+        payload:
+          schemaFormat: 'application/vnd.aai.asyncapi;version=3.1.0'
+          schema:
+            type: object
+            required: [offset]
+            additionalProperties: false
+            properties:
+              offset:
+                type: number
+operations:
+  sendReading:
+    action: send
+    channel:
+      $ref: '#/channels/reading'
+  receiveCalibrate:
+    action: receive
+    channel:
+      $ref: '#/channels/calibrate'
+```
+
+- [ ] **Step 2: Write the failing regression test**
+
+Append to `src/registry/index.test.ts`:
+
+```ts
+// [utest->R-038]
+test("a multi-format payload still VALIDATES (the wrapper must be unwrapped)", async () => {
+	const reg = await registryFor("multi-format.yaml");
+	const reading = reg.match("reading/s1")?.channel;
+	expect(reading).toBeDefined();
+	// the schema handed to Ajv must be the payload schema, not the wrapper
+	expect(Object.keys(reading?.schema as object)).not.toContain("schemaFormat");
+	expect(Object.keys(reading?.schema as object)).not.toContain("schema");
+	// conforming payload passes
+	expect(reading?.validate({ sensorId: "s1", celsius: 21.5 })).toEqual([]);
+	// and the tripwire: garbage must NOT pass. Before the unwrap every one of
+	// these validated green, which is the false-negative class R-028 forbids.
+	expect(reading?.validate({ sensorId: 42, celsius: "hot" }).length).toBeGreaterThan(0);
+	expect(reading?.validate({ unrelated: true }).length).toBeGreaterThan(0);
+	expect(reading?.validate("not-an-object").length).toBeGreaterThan(0);
+	expect(reading?.validate(null).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("the multi-format wrapper is unwrapped on the client-publish path too", async () => {
+	const reg = await registryFor("multi-format.yaml");
+	const calibrate = reg.match("calibrate/s1")?.channel;
+	expect(calibrate?.direction).toBe("fromClient");
+	expect(calibrate?.validate({ offset: 0.5 })).toEqual([]);
+	expect(calibrate?.validate({ offset: "half" }).length).toBeGreaterThan(0);
+	expect(calibrate?.validate({}).length).toBeGreaterThan(0);
+});
+```
+
+- [ ] **Step 3: Run it to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: both new tests FAIL. The schema's top-level keys are `$schema, schemaFormat, schema`, and every garbage payload validates green.
+
+- [ ] **Step 4: Implement the extraction**
+
+In `src/registry/index.ts`, add this function beside `directionOf`:
+
+```ts
+// AsyncAPI 3.x lets a payload be a Multi Format Schema Object (`{schemaFormat,
+// schema}`), permitted even for the default JSON-Schema format. `BaseModel.json()`
+// returns that wrapper verbatim (the parser's own Schema model unwraps
+// `_json.schema` internally for its typed accessors), so spreading it yields a
+// schema with NO validation keywords: a validator that accepts everything (D-018).
+// Deliberately does NOT branch on the schemaFormat STRING: the implementation
+// emits `application/vnd.aai.asyncapi;version=X` while the spec text mandates a
+// `+json` suffix, so a literal comparison would silently stop matching.
+function extractPayloadSchema(payloadJson: unknown): object {
+	if (payloadJson === null || typeof payloadJson !== "object") return {};
+	const p = payloadJson as Record<string, unknown>;
+	if ("schemaFormat" in p && typeof p.schema === "object" && p.schema !== null) {
+		return p.schema as object;
+	}
+	return p;
+}
+```
+
+Then replace the schema construction inside the operation loop. Change:
+
+```ts
+		const schema = {
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			...((msg?.payload()?.json() ?? {}) as object),
+		};
+```
+
+to:
+
+```ts
+		const schema = {
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			...extractPayloadSchema(msg?.payload()?.json()),
+		};
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts fixtures/asyncapi/multi-format.yaml
+git commit -m "fix(registry): unwrap the Multi Format Schema Object payload (R-038)
+
+A valid AsyncAPI 3.x payload authored as {schemaFormat, schema} produced a
+channel schema with no validation keywords, so it accepted everything including
+null and bare strings: a silent false negative on a supported version. Extract
+the inner schema, and pin it with a multi-format.yaml fixture whose garbage
+payloads must be rejected on both the send and receive paths."
+```
+
+---
+
+### Task 3: Validate under draft-07
+
+Root-cause fix for the tuple crash and the silently-ignored `additionalItems`, and the reason D-005's obligation closes.
+
+**Files:**
+- Modify: `src/registry/index.ts`, `fixtures/asyncapi/composition.yaml`, `fixtures/asyncapi/external-ref.yaml`, `docs/specs/contracts.md`, `DECISIONS.md`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: `extractPayloadSchema` from Task 2.
+- Produces: module constant `DRAFT_07 = "http://json-schema.org/draft-07/schema#"`, and every `Channel.schema` now carries that `$schema` value. Tasks 6 and 7 reuse `DRAFT_07`.
+
+- [ ] **Step 1: Add a tuple payload to the composition fixture**
+
+`composition.yaml` is the schema-shapes fixture, so the tuple case belongs there. Add a third channel and its operation, matching the file's existing indentation and comment style. Read the file first to place these consistently; the `window` channel below is additive and must not disturb the existing `allOf`/`oneOf`/`anyOf` channels.
+
+Add under `channels:`:
+
+```yaml
+  window:
+    address: window/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Window:
+        name: Window
+        payload:
+          # Draft-07 TUPLE validation: `items` as an ARRAY constrains positions.
+          # Legal in both spec majors (the Schema Object is a draft-07 superset),
+          # but it made ajv.compile() THROW while offbook stamped 2020-12, which
+          # renamed the tuple form to `prefixItems` (D-018). Under draft-07 it
+          # validates positionally, and `additionalItems` is honored.
+          type: array
+          items:
+            - type: string
+            - type: number
+          additionalItems: false
+```
+
+Add under `operations:`:
+
+```yaml
+  sendWindow:
+    action: send
+    channel:
+      $ref: '#/channels/window'
+```
+
+> **AMENDED DURING EXECUTION (2026-07-30).** Steps 1 and 1b below were **not** taken. Implementation measured that **json-schema-faker 0.6.2 cannot draw a valid draft-07 tuple**: it emits objects with numeric keys (for example `[{"0":"aG88rL","1":441.48}, ...]`) and fails the Ajv recheck **10/10 seeds**, unchanged by `additionalItems` or `minItems`. A tuple channel in `composition.yaml` therefore fails the R-027 faker-floor spike and would flip **D-008**'s measured verdict, which is a separate question from the dialect. The tuple regression case was implemented as an **inline test spec** in `src/registry/index.test.ts` instead, `composition.yaml` and the spike expectation were left untouched, and the finding is recorded in D-018 with the keyed-fallback question left open. Steps 2 onward were followed as written.
+
+- [ ] ~~**Step 1b: Re-measure the spike expectation for composition.yaml**~~ (superseded, see above)
+
+Adding the `window` channel gives `composition.yaml` a third channel, so the R-027 tripwire's pinned draw count changes (see the Global Constraints bullet on this coupling). In `test/spikes/jsf-fidelity.test.ts`, update the `composition.yaml` entry from `{ draws: 20, failures: 0 }` to the freshly measured value, which should be `{ draws: 30, failures: 0 }` for three channels at ten seeds each, and add a comment noting the re-measurement and citing D-018.
+
+**Measure, do not assume.** Run the suite and read the actual numbers rather than trusting the arithmetic. If `failures` comes back non-zero, STOP and report: it would mean json-schema-faker cannot draw valid data for a draft-07 tuple, which is a genuine finding about the dialect change and not something to paper over by adjusting the expectation.
+
+No fixture is being added here, so `SPIKE_FIXTURES` itself needs no change.
+
+- [ ] **Step 2: Write the failing dialect tests**
+
+Append to `src/registry/index.test.ts`:
+
+```ts
+// [utest->R-038]
+test("draft-07 tuple `items` validates positionally instead of crashing the build", async () => {
+	const reg = await registryFor("composition.yaml");
+	const window = reg.match("window/s1")?.channel;
+	expect(window).toBeDefined();
+	expect(window?.validate(["a", 1])).toEqual([]);
+	// wrong order and wrong type at position 1 are both caught
+	expect(window?.validate([1, "a"]).length).toBeGreaterThan(0);
+	expect(window?.validate(["a", "b"]).length).toBeGreaterThan(0);
+	// additionalItems: false is honored under draft-07 (2020-12 ignores it)
+	expect(window?.validate(["a", 1, "extra"]).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("channel schemas declare the draft-07 dialect they are validated under", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	const schema = reg.channels()[0].schema as { $schema?: string };
+	expect(schema.$schema).toBe("http://json-schema.org/draft-07/schema#");
+});
+```
+
+- [ ] **Step 3: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: FAIL. The tuple test fails hard, because `ajv.compile()` throws `schema is invalid: data/items must be object,boolean` while building the `composition.yaml` registry, which will surface as an error from `registryFor` rather than an assertion failure. The `$schema` test fails on the 2020-12 value.
+
+- [ ] **Step 4: Switch the dialect**
+
+In `src/registry/index.ts`, replace the Ajv import:
+
+```ts
+import Ajv2020 from "ajv/dist/2020";
+```
+
+with:
+
+```ts
+import Ajv from "ajv";
+```
+
+Add the constant beside `extractPayloadSchema`:
+
+```ts
+// The dialect BOTH spec majors declare for the Schema Object ("a superset of
+// JSON Schema Draft 07") and the one @asyncapi/parser actually emits. Stamping
+// 2020-12 over it was the root cause of the tuple-compile crash and of
+// `additionalItems` being silently ignored (D-018). Stamped explicitly so
+// `channel.schema`, which GET /topics hands out, is self-describing.
+const DRAFT_07 = "http://json-schema.org/draft-07/schema#";
+```
+
+Replace the Ajv construction:
+
+```ts
+	const ajv = addFormats(new Ajv2020({ allErrors: true, strict: false }));
+```
+
+with:
+
+```ts
+	const ajv = addFormats(new Ajv({ allErrors: true, strict: false }));
+```
+
+And the stamp:
+
+```ts
+		const schema = {
+			$schema: DRAFT_07,
+			...extractPayloadSchema(msg?.payload()?.json()),
+		};
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0, including the pre-existing `external-ref` tests and the D-005 tripwire, whose behavior is unchanged under draft-07 (the external `pattern` is still enforced, the `$ref` sibling `minLength` is still not).
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`. If `src/engine/faker.test.ts` or the R-027 spike test fails, stop: it would mean json-schema-faker draws differently for the new tuple channel. Investigate before proceeding rather than adjusting seeds.
+
+- [ ] **Step 6: Reword the D-005 tripwire comment in the fixture**
+
+In `fixtures/asyncapi/external-ref.yaml`, the comment above `minLength: 3` currently frames the dropped sibling as a limitation awaiting a 2020-12 spike. Replace that comment block with:
+
+```yaml
+          # A 2020-12 reader would honor this `minLength` beside the `$ref`; a draft-07
+          # reader ignores `$ref` siblings, and draft-07 is the dialect BOTH spec majors
+          # declare and the parser emits, so offbook validating under it means the sibling
+          # is correctly NOT enforced (D-018 supersedes D-005's deferred 2020-12 spike).
+          # The external `pattern` IS inlined and enforced. The tripwire in
+          # registry/index.test.ts pins this so a future dialect change is loud.
+```
+
+Update the corresponding tripwire test comment in `src/registry/index.test.ts` from "KNOWN LIMITATION (D-005 …)" to reference D-018 as dialect-correct behavior. Keep the assertions exactly as they are.
+
+- [ ] **Step 7: Reverse the dialect statement in the canonical contract**
+
+`docs/specs/contracts.md` §5 currently says the bundled schema is handed to Ajv with only a 2020-12 stamp (search for `2020-12` and for `$schema`). Contracts is canonical, so this must change, not merely the guide. Replace each 2020-12 assertion about the payload dialect with the draft-07 statement, for example:
+
+> **`Channel.schema` is validated under JSON Schema draft-07**, the dialect both AsyncAPI majors declare for the Schema Object and the one `@asyncapi/parser` emits; `registry/` stamps `$schema: http://json-schema.org/draft-07/schema#` explicitly so the schema `GET /topics` hands out is self-describing (D-018). Keywords added after draft-07 (`prefixItems`, `unevaluatedProperties`, `dependentRequired`, and friends) cannot be honored and are surfaced as a `spec-load` diagnostic rather than silently ignored.
+
+Leave the surrounding bundling requirements (parser-provided, never hand-rolled `$ref` walking, R1) intact.
+
+- [ ] **Step 8: Add the superseded note to D-005**
+
+In `DECISIONS.md`, append to `D-005`'s `Obligations (deferred spike)` field:
+
+```markdown
+**Superseded by**: D-018 (2026-07-30). offbook now validates under draft-07, the dialect both majors declare and the parser emits, so the dropped `$ref` sibling is dialect-correct behavior rather than a limitation, and the 2020-12 schema-parser spike is no longer an obligation. The tripwire is retained and reworded so a future dialect change stays loud.
+```
+
+- [ ] **Step 9: Verify all gates**
+
+Run: `bun scripts/check-docs.ts; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+Run: `bun test; echo "EXIT=$?"` then `bun run lint && bun run typecheck; echo "EXIT=$?"`
+Expected: `EXIT=0` for both.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts fixtures/asyncapi/composition.yaml fixtures/asyncapi/external-ref.yaml docs/specs/contracts.md DECISIONS.md
+git commit -m "fix(registry): validate payloads under draft-07, not 2020-12 (R-038)
+
+Both spec majors define the Schema Object as a draft-07 superset and the parser
+emits draft-07, so stamping 2020-12 was the root cause of a legal tuple schema
+crashing ajv.compile() and of additionalItems being silently ignored. Verified
+the external-ref bar and the D-005 tripwire behave identically.
+
+Reverses the 2020-12 statement in contracts.md §5 (canonical) and closes
+D-005's deferred obligation as superseded by D-018."
+```
+
+---
+
+### Task 4: A diagnostics channel on the registry
+
+Plumbing plus its first consumer. Registry-time findings cannot be recomputed from `Channel` alone, so the registry carries them out.
+
+**Files:**
+- Modify: `src/model/index.ts`, `src/registry/index.ts`, `src/compose/index.ts`, `docs/specs/contracts.md`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: nothing new.
+- Produces: `SpecRegistry.diagnostics(): readonly Diagnostic[]`. Both `buildRegistry` and `mergeRegistries` implement it. Tasks 5, 6, and 8 push into the same array. Diagnostic `detail` strings begin with a stable tag followed by `: `.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/registry/index.test.ts`:
+
+```ts
+// [utest->R-039]
+test("an mqtt CHANNEL binding is reported as ignored, not silently dropped", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/chanbound
+    bindings: { mqtt: { qos: 2, retain: true } }
+    messages: { M: { payload: { type: object, properties: { a: { type: string } } } } }
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	// MQTT defines qos/retain on the OPERATION only: the Channel Binding Object
+	// "MUST NOT contain any properties" at every binding version, so the values
+	// are ignored and the channel keeps the global defaults.
+	expect(reg.match("t/chanbound")?.channel.qos).toBe(1);
+	const found = reg.diagnostics().filter((d) => d.detail.startsWith("binding-on-channel:"));
+	expect(found.length).toBe(1);
+	expect(found[0].kind).toBe("spec-load");
+	expect(found[0].severity).toBe("warning");
+	expect(found[0].source).toBe("t/chanbound");
+});
+
+// [utest->R-039]
+test("a clean spec produces no registry diagnostics", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	expect(reg.diagnostics()).toEqual([]);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: FAIL, `reg.diagnostics is not a function`.
+
+- [ ] **Step 3: Add `diagnostics()` to the contract type**
+
+In `src/model/index.ts`, extend the interface:
+
+```ts
+export interface SpecRegistry {
+	match(
+		topic: string,
+	): { channel: Channel; params: Record<string, string> } | undefined;
+	matchesFilter(filter: string, topic: string): boolean;
+	channels(): readonly Channel[];
+	// Registry-time spec-QUALITY findings (D-018): problems discoverable only
+	// while building the catalog, so they cannot be recomputed from Channel
+	// later (binding placement, dialect mismatch, a schema that would not
+	// compile). Collected once at build; the composition root merges them into
+	// GET /v1/diagnostics beside the computed ones. Uses the existing closed
+	// `spec-load` kind with a machine-greppable `detail` tag prefix.
+	diagnostics(): readonly Diagnostic[];
+}
+```
+
+`Diagnostic` is declared later in the same file, which is fine for a TypeScript interface reference.
+
+- [ ] **Step 4: Collect and expose diagnostics in the registry**
+
+In `src/registry/index.ts`, add `Diagnostic` to the type import from `#src/model/index.ts`.
+
+Declare the array beside `const channels: Channel[] = [];`:
+
+```ts
+	const diagnostics: Diagnostic[] = [];
+```
+
+Inside the operation loop, after `const address = ch.address() ?? "";`, add the first consumer:
+
+```ts
+		// MQTT defines qos/retain on the OPERATION binding only: the Channel
+		// Binding Object "MUST NOT contain any properties. Its name is reserved
+		// for future use." at every binding version. A channel-level mqtt binding
+		// nonetheless parses clean, so say it is ignored rather than defaulting
+		// in silence (D-018).
+		const channelMqtt = ch.bindings().get("mqtt")?.value<Record<string, unknown>>();
+		if (channelMqtt && Object.keys(channelMqtt).length > 0) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-on-channel: '${address}' declares an mqtt CHANNEL binding (${Object.keys(
+					channelMqtt,
+				).join(", ")}); MQTT defines qos/retain on the operation only, so these are ignored`,
+				source: address,
+			});
+		}
+```
+
+Add to the returned object in `buildRegistry`:
+
+```ts
+		diagnostics: () => diagnostics,
+```
+
+And to `mergeRegistries`'s returned object:
+
+```ts
+		diagnostics: () => registries.flatMap((r) => [...r.diagnostics()]),
+```
+
+- [ ] **Step 5: Run to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+- [ ] **Step 6: Wire the diagnostics into the control plane**
+
+In `src/compose/index.ts`, add the registry's diagnostics to the list at lines 183-190:
+
+```ts
+		diagnostics: () => [
+			...(runtime?.diagnostics() ?? []),
+			...registry.diagnostics(),
+			...specQualityDiagnostics(registry.channels()),
+			...uninstantiatedDiagnostics(
+				registry.channels(),
+				engine.instances.snapshot(),
+			),
+		],
+```
+
+- [ ] **Step 7: Document the contract change**
+
+In `docs/specs/contracts.md`, add `diagnostics()` to the `SpecRegistry` interface block (around line 45-49) with a short comment, and note in §5's diagnostics prose that `spec-load` entries now also carry registry-time findings tagged by a `detail` prefix (`binding-on-channel`, `binding-invalid-value`, `binding-unknown-key`, `mqtt5-field-ignored`, `dialect-mismatch`, `schema-compile-failed`).
+
+- [ ] **Step 8: Verify all gates**
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`. If any test builds a fake `SpecRegistry` object literal, it will now fail to typecheck for a missing `diagnostics`; add `diagnostics: () => []` to those fakes.
+
+Run: `bun run lint && bun run typecheck && bun scripts/check-docs.ts; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/model/index.ts src/registry/index.ts src/registry/index.test.ts src/compose/index.ts docs/specs/contracts.md
+git commit -m "feat(registry): carry registry-time diagnostics to /v1/diagnostics (R-039)
+
+Registry-time findings cannot be recomputed from Channel, so SpecRegistry gains
+diagnostics(), merged by the composition root beside the computed ones. First
+consumer: an mqtt CHANNEL binding, which is illegal per the binding spec at
+every version yet parses clean, is now reported as ignored instead of silently
+falling back to the default qos."
+```
+
+---
+
+### Task 5: Diagnose keywords draft-07 cannot honor
+
+Draft-07 ignores unknown keywords, so a 2020-12-authored payload would silently under-validate. This makes that loud.
+
+**Files:**
+- Modify: `src/registry/index.ts`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: the `diagnostics` array from Task 4.
+- Produces: diagnostics tagged `dialect-mismatch: `.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/registry/index.test.ts`:
+
+```ts
+// [utest->R-038]
+test("post-draft-07 keywords are surfaced, since draft-07 ignores them silently", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/modern
+    messages:
+      M:
+        payload:
+          type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              prefixItems:
+                - type: string
+          unevaluatedProperties: false
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const found = reg.diagnostics().filter((d) => d.detail.startsWith("dialect-mismatch:"));
+	expect(found.length).toBe(1);
+	expect(found[0].severity).toBe("warning");
+	expect(found[0].source).toBe("t/modern");
+	// names every offending keyword so the author can fix them all at once
+	expect(found[0].detail).toContain("prefixItems");
+	expect(found[0].detail).toContain("unevaluatedProperties");
+});
+
+// [utest->R-038]
+test("$defs and definitions are NOT reported: both work under draft-07", async () => {
+	// the repo's own shared/common.yaml uses $defs, so flagging it would cry wolf
+	const reg = await registryFor("external-ref.yaml");
+	expect(reg.diagnostics().filter((d) => d.detail.startsWith("dialect-mismatch:"))).toEqual([]);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: the first new test FAILS, `found.length` is 0.
+
+- [ ] **Step 3: Implement the scan**
+
+In `src/registry/index.ts`, add beside `DRAFT_07`:
+
+```ts
+// Keywords JSON Schema introduced after draft-07. offbook validates under
+// draft-07, where these are unknown and therefore SILENTLY IGNORED, which is
+// the worst failure mode for a contract checker, so their presence is surfaced
+// (D-018). `$defs` and `definitions` are deliberately absent: both resolve
+// correctly under draft-07, and fixtures/asyncapi/shared/common.yaml
+// legitimately uses `$defs`.
+const POST_DRAFT07_KEYWORDS = new Set([
+	"prefixItems",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"dependentRequired",
+	"dependentSchemas",
+	"minContains",
+	"maxContains",
+	"$dynamicRef",
+	"$dynamicAnchor",
+	"$recursiveRef",
+	"$recursiveAnchor",
+]);
+
+function postDraft07Keywords(
+	node: unknown,
+	found: Set<string> = new Set(),
+): Set<string> {
+	if (Array.isArray(node)) {
+		for (const item of node) postDraft07Keywords(item, found);
+		return found;
+	}
+	if (node === null || typeof node !== "object") return found;
+	for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+		if (POST_DRAFT07_KEYWORDS.has(key)) found.add(key);
+		postDraft07Keywords(value, found);
+	}
+	return found;
+}
+```
+
+Inside the operation loop, after `const schema = { ... }`, add:
+
+```ts
+		const modernKeywords = postDraft07Keywords(schema);
+		if (modernKeywords.size > 0) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `dialect-mismatch: '${address}' uses post-draft-07 keyword(s) ${[
+					...modernKeywords,
+				]
+					.sort()
+					.join(", ")}; offbook validates under draft-07 (the dialect both AsyncAPI majors declare), so these are NOT enforced`,
+				source: address,
+			});
+		}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts
+git commit -m "feat(registry): diagnose post-draft-07 keywords (R-038)
+
+Draft-07 ignores prefixItems, unevaluatedProperties, dependentRequired and
+friends rather than erroring, which would under-validate silently. Name every
+offending keyword per channel. \$defs and definitions are excluded: both work
+under draft-07 and shared/common.yaml uses \$defs."
+```
+
+---
+
+### Task 6: Contain a schema that will not compile
+
+**Files:**
+- Modify: `src/registry/index.ts`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: `DRAFT_07`, the `diagnostics` array.
+- Produces: a channel whose `validate` returns one `SchemaError` with `keyword: "offbook:schema-compile-failed"`.
+
+- [ ] **Step 1: Write the failing test**
+
+This needs a payload the AsyncAPI parser **accepts** but Ajv refuses to compile, which is a narrow set: the parser validates payloads against the draft-07-based Schema Object meta-schema, so most malformed schemas (`minLength: not-a-number`, `multipleOf: 0`, `type: 17`, `required: nope`) are rejected at parse and never reach Ajv. **An invalid regex is the realistic case**: `pattern: '['` satisfies the meta-schema (which treats `format: regex` as an annotation) and then makes Ajv throw `Invalid regular expression: missing terminating ] for character class`. Verified during planning; do not substitute another shape without re-checking it the same way.
+
+```ts
+// [utest->R-038]
+test("a schema that will not compile yields violations, never a crash and never green", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/broken
+    messages:
+      M:
+        payload:
+          type: object
+          properties:
+            bad:
+              type: string
+              pattern: '['
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	// does not throw: discovery is a v1 floor that must survive a weak spec
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const broken = reg.match("t/broken")?.channel;
+	expect(broken).toBeDefined();
+	// and it must NOT validate green, which would be false confidence
+	const errs = broken?.validate({ anything: true }) ?? [];
+	expect(errs.length).toBe(1);
+	expect(errs[0].keyword).toBe("offbook:schema-compile-failed");
+	const found = reg.diagnostics().filter((d) => d.detail.startsWith("schema-compile-failed:"));
+	expect(found.length).toBe(1);
+	expect(found[0].severity).toBe("error");
+	expect(found[0].source).toBe("t/broken");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: FAIL. `buildRegistry` rejects with a raw Ajv error rather than returning a registry.
+
+If instead the test fails because the document did not parse at all, the payload was caught by the parser's meta-schema rather than by Ajv, and the test is measuring the wrong thing. Re-confirm the shape with:
+
+```bash
+bun -e 'import Ajv from "ajv"; const a=new Ajv({strict:false}); try{a.compile({type:"object",properties:{bad:{type:"string",pattern:"["}}});console.log("COMPILED (pick another shape)")}catch(e){console.log("REJECTS:",e.message.slice(0,80))}'
+```
+
+Expected: `REJECTS: Invalid regular expression: …`.
+
+- [ ] **Step 3: Wrap the compile**
+
+In `src/registry/index.ts`, replace:
+
+```ts
+		const validateFn = ajv.compile(schema);
+```
+
+with:
+
+```ts
+		// A schema Ajv refuses must never validate GREEN: that is false
+		// confidence, the failure mode this tool exists to prevent. The channel
+		// still enters the catalog because discovery is a v1 floor that survives
+		// weak specs, but every payload on it reports one explicit violation
+		// (D-018).
+		let validate: (payload: unknown) => SchemaError[];
+		try {
+			const validateFn = ajv.compile(schema);
+			validate = (payload: unknown): SchemaError[] =>
+				validateFn(payload) ? [] : ((validateFn.errors ?? []) as SchemaError[]);
+		} catch (cause) {
+			const reason = (cause as Error).message;
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "error",
+				detail: `schema-compile-failed: '${address}' payload schema did not compile, so nothing on this channel is validated: ${reason}`,
+				source: address,
+			});
+			const compileError: SchemaError = {
+				instancePath: "",
+				schemaPath: "#",
+				keyword: "offbook:schema-compile-failed",
+				params: {},
+				message: `payload schema did not compile: ${reason}`,
+			};
+			validate = () => [compileError];
+		}
+```
+
+Then replace the inline `validate` in the `channels.push({ … })` call:
+
+```ts
+			validate: (payload: unknown): SchemaError[] =>
+				validateFn(payload) ? [] : ((validateFn.errors ?? []) as SchemaError[]),
+```
+
+with:
+
+```ts
+			validate,
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+Run: `bun test; echo "EXIT=$?"` then `bun run typecheck; echo "EXIT=$?"`
+Expected: `EXIT=0` for both.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts
+git commit -m "fix(registry): contain an uncompilable payload schema (R-038)
+
+ajv.compile() threw out of buildRegistry uncaught, surfacing as a raw Ajv error
+from bootProject with no channel named. Wrap it: the channel still enters the
+catalog, because discovery is a v1 floor, but every payload reports one explicit
+offbook:schema-compile-failed violation rather than validating green, and the
+failure is surfaced as a spec-load diagnostic naming the topic."
+```
+
+---
+
+### Task 7: Validate every declared message, not just the first
+
+**Files:**
+- Modify: `src/registry/index.ts`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: `extractPayloadSchema`, `DRAFT_07`.
+- Produces: for an operation with more than one message, `Channel.schema` is `{$schema, anyOf: [...]}`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// [utest->R-038]
+test("a v2 message.oneOf union validates EITHER variant, not just the first", async () => {
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/union:
+    subscribe:
+      operationId: s
+      message:
+        oneOf:
+          - payload: { type: object, required: [a], additionalProperties: false, properties: { a: { type: string } } }
+          - payload: { type: object, required: [b], additionalProperties: false, properties: { b: { type: number } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const union = reg.match("t/union")?.channel;
+	expect(union?.validate({ a: "x" })).toEqual([]);
+	// before the anyOf, variant two was reported as a violation because only
+	// messages()[0] was read
+	expect(union?.validate({ b: 2 })).toEqual([]);
+	// and something matching NEITHER variant is still caught
+	expect(union?.validate({ c: true }).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("a single-message operation keeps its schema unwrapped by anyOf", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	const schema = reg.channels()[0].schema as Record<string, unknown>;
+	expect(schema.anyOf).toBeUndefined();
+	expect(schema.type).toBe("object");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: the union test FAILS on `union?.validate({ b: 2 })`, which returns errors because only the first message's schema is compiled.
+
+- [ ] **Step 3: Build the anyOf**
+
+In `src/registry/index.ts`, replace:
+
+```ts
+		const msg = op.messages().all()[0];
+```
+
+with:
+
+```ts
+		// An MQTT topic can legitimately carry one of several declared message
+		// types (a v2 `message.oneOf` union, or a v3 operation listing several
+		// messages). Reading only messages()[0] reported every other variant as a
+		// violation. `anyOf` keeps Channel.schema singular, so the faker and
+		// /topics are unaffected (D-018).
+		const messages = op.messages().all();
+		const msg = messages[0];
+		const payloadSchemas = messages.map((m) =>
+			extractPayloadSchema(m.payload()?.json()),
+		);
+```
+
+and replace the schema construction:
+
+```ts
+		const schema = {
+			$schema: DRAFT_07,
+			...extractPayloadSchema(msg?.payload()?.json()),
+		};
+```
+
+with:
+
+```ts
+		const schema =
+			payloadSchemas.length > 1
+				? { $schema: DRAFT_07, anyOf: payloadSchemas }
+				: { $schema: DRAFT_07, ...(payloadSchemas[0] ?? {}) };
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`. Watch `src/engine/faker.test.ts` and the R-027 spike test: json-schema-faker must still draw Ajv-valid data. `composition.yaml` already exercises `anyOf` with zero recheck failures, so this path is known good; if a faker test fails, stop and investigate rather than adjusting seeds.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts
+git commit -m "fix(registry): validate all of an operation's messages as anyOf (R-038)
+
+Only messages()[0] was compiled, so a v2 message.oneOf union or a v3
+multi-message operation reported every non-first variant as a contract
+violation. anyOf keeps Channel.schema singular, leaving the faker and /topics
+untouched."
+```
+
+---
+
+### Task 8: MQTT binding integrity
+
+Closes the 2.x unvalidated-binding hole without a converter, and reports what MQTT 3.1.1 cannot honor.
+
+**Files:**
+- Create: `fixtures/asyncapi/v2-oldest.yaml`
+- Modify: `src/registry/index.ts`
+- Test: `src/registry/index.test.ts`
+
+**Interfaces:**
+- Consumes: the `diagnostics` array.
+- Produces: diagnostics tagged `binding-invalid-value: `, `binding-unknown-key: `, `mqtt5-field-ignored: `. A rejected binding value falls through to the next tier of the existing §2 precedence chain.
+
+- [ ] **Step 1: Create the oldest-major fixture**
+
+Create `fixtures/asyncapi/v2-oldest.yaml`. `qos: 2` differs from the global default (1) and from any per-service default, so the assertion is not vacuous (quality-bar item 1).
+
+```yaml
+asyncapi: '2.0.0'
+info:
+  title: Oldest Supported Major
+  version: 1.0.0
+  description: >-
+    AsyncAPI 2.0.0, the FLOOR of offbook's supported range (D-018). Pins that
+    the oldest major still parses, that `publish`/`subscribe` normalize to
+    fromClient/toClient, and that a 2.x mqtt OPERATION binding is read (2.x maps
+    `mqtt` to an empty schema in its own meta-schema, so nothing validates it
+    upstream: offbook checks the values and keys itself).
+servers:
+  mosquitto:
+    url: localhost:1883
+    protocol: mqtt
+    protocolVersion: '3.1.1'
+channels:
+  legacy/{deviceId}/telemetry:
+    parameters:
+      deviceId:
+        schema:
+          type: string
+    subscribe:                     # service publishes ⇒ client receives ⇒ toClient
+      operationId: sendTelemetry
+      bindings:
+        mqtt:
+          qos: 2                   # differs from the global default (1): a real assertion
+          retain: true
+          bindingVersion: '0.1.0'
+      message:
+        $ref: '#/components/messages/Telemetry'
+  legacy/{deviceId}/command:
+    parameters:
+      deviceId:
+        schema:
+          type: string
+    publish:                       # client publishes ⇒ service receives ⇒ fromClient
+      operationId: receiveCommand
+      message:
+        $ref: '#/components/messages/Command'
+components:
+  messages:
+    Telemetry:
+      name: Telemetry
+      payload:
+        type: object
+        required: [deviceId, celsius]
+        additionalProperties: false
+        properties:
+          deviceId:
+            type: string
+          celsius:
+            type: number
+    Command:
+      name: Command
+      payload:
+        type: object
+        required: [mode]
+        additionalProperties: false
+        properties:
+          mode:
+            type: string
+            enum: [heat, cool, off]
+```
+
+- [ ] **Step 1b: Register the new fixture with the spike tripwire**
+
+`v2-oldest.yaml` joins `fixtures/asyncapi/`, so the R-027 tripwire goes red until it is registered (see the Global Constraints bullet on this coupling; Task 2 hit the same thing with `multi-format.yaml`). Add `"v2-oldest.yaml"` to `SPIKE_FIXTURES` in `scripts/spike-jsf-fidelity.ts`, keeping the list alphabetically sorted, and add a measured `EXPECTED` entry in `test/spikes/jsf-fidelity.test.ts` with a comment citing D-018. Two channels at ten seeds each should give `{ draws: 20, failures: 0 }`.
+
+**Measure, do not assume**, and if `failures` is non-zero, STOP and report rather than adjusting the expectation. Include both files in this task's `git add`.
+
+- [ ] **Step 2: Write the failing tests**
+
+```ts
+// [utest->R-039]
+test("the oldest supported major parses, inverts direction, and its binding is read", async () => {
+	const reg = await registryFor("v2-oldest.yaml");
+	const telemetry = reg.match("legacy/d1/telemetry")?.channel;
+	const command = reg.match("legacy/d1/command")?.channel;
+	// v2 subscribe = messages PRODUCED by the application (the service) ⇒ toClient
+	expect(telemetry?.direction).toBe("toClient");
+	// v2 publish = messages CONSUMED by the application ⇒ the client sends them
+	expect(command?.direction).toBe("fromClient");
+	expect(telemetry?.qos).toBe(2);
+	expect(telemetry?.retain).toBe(true);
+	expect(reg.diagnostics()).toEqual([]);
+});
+
+// [utest->R-039]
+test("an out-of-range binding qos is rejected and falls through the precedence chain", async () => {
+	// 2.x maps `mqtt` to an empty schema, so qos 9 parses clean upstream and
+	// would otherwise reach a Channel typed 0 | 1 | 2
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/bad:
+    subscribe:
+      operationId: s
+      bindings:
+        mqtt: { qos: 9, retain: "yes" }
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+		serviceConfig: { repo: "x", specPath: "y", qosDefault: 0, retainDefault: true },
+	});
+	const ch = reg.match("t/bad")?.channel;
+	// falls through to the per-service default (tier 3), NOT clamped and NOT propagated
+	expect(ch?.qos).toBe(0);
+	expect(ch?.retain).toBe(true);
+	const bad = reg.diagnostics().filter((d) => d.detail.startsWith("binding-invalid-value:"));
+	expect(bad.length).toBe(2);
+	expect(bad.every((d) => d.severity === "warning")).toBe(true);
+});
+
+// [utest->R-039]
+test("a misspelled binding key is reported against the official key set", async () => {
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/typo:
+    subscribe:
+      operationId: s
+      bindings:
+        mqtt: { qos: 1, retian: true }
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const unknown = reg.diagnostics().filter((d) => d.detail.startsWith("binding-unknown-key:"));
+	expect(unknown.length).toBe(1);
+	expect(unknown[0].detail).toContain("retian");
+});
+
+// [utest->R-039]
+test("MQTT-5-only binding fields are reported as unhonored", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/five, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o:
+    action: send
+    channel: { $ref: '#/channels/c' }
+    bindings: { mqtt: { qos: 1, messageExpiryInterval: 60 } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const five = reg.diagnostics().filter((d) => d.detail.startsWith("mqtt5-field-ignored:"));
+	expect(five.length).toBe(1);
+	expect(five[0].detail).toContain("messageExpiryInterval");
+	expect(five[0].severity).toBe("info");
+});
+```
+
+- [ ] **Step 3: Run to verify it fails**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: FAIL. `qos: 9` currently propagates, and no binding diagnostics exist.
+
+- [ ] **Step 4: Implement binding integrity**
+
+In `src/registry/index.ts`, add the import at the top with the other imports:
+
+```ts
+import mqttOperationBinding from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with {
+	type: "json",
+};
+```
+
+Add the constants beside `POST_DRAFT07_KEYWORDS`:
+
+```ts
+// The legal key set comes from the OFFICIAL binding schema rather than a
+// hardcoded list, so it tracks upstream. Only `properties` is read: the schema
+// cannot be compiled standalone (it $refs
+// http://asyncapi.com/definitions/3.0.0/schema.json, resolvable only inside the
+// bundled spec schema), and offbook consumes just qos and retain anyway.
+// Validating against 0.2.0 is permissive-correct: its property set is a
+// superset of 0.1.0's.
+const MQTT_OPERATION_KEYS = new Set(
+	Object.keys(
+		(mqttOperationBinding as { properties: Record<string, unknown> }).properties,
+	),
+);
+
+// MQTT 5 only, per the "MQTT Versions" column of the binding spec. offbook is
+// MQTT 3.1.1 only, so these can never be honored and saying so beats silence.
+const MQTT5_ONLY_KEYS = new Set([
+	"messageExpiryInterval",
+	"payloadFormatIndicator",
+	"correlationData",
+	"contentType",
+	"responseTopic",
+	"sessionExpiryInterval",
+	"maximumPacketSize",
+]);
+```
+
+Replace the typed binding read:
+
+```ts
+		const mqtt = op.bindings().get("mqtt")?.value<{
+			qos?: 0 | 1 | 2;
+			retain?: boolean;
+		}>();
+```
+
+with an untyped read plus the guards:
+
+```ts
+		// Read untyped: 2.x maps `mqtt` to an EMPTY schema in its own
+		// meta-schema, so nothing upstream validated these values and a declared
+		// type here would be a lie (D-018).
+		const mqtt = op.bindings().get("mqtt")?.value<Record<string, unknown>>();
+		if (mqtt) {
+			const unknownKeys = Object.keys(mqtt).filter(
+				(k) => !MQTT_OPERATION_KEYS.has(k),
+			);
+			if (unknownKeys.length > 0) {
+				diagnostics.push({
+					kind: "spec-load",
+					severity: "warning",
+					detail: `binding-unknown-key: '${address}' mqtt operation binding has unknown key(s) ${unknownKeys
+						.sort()
+						.join(", ")}; the mqtt binding defines ${[...MQTT_OPERATION_KEYS]
+						.sort()
+						.join(", ")}`,
+					source: address,
+				});
+			}
+			const five = Object.keys(mqtt).filter((k) => MQTT5_ONLY_KEYS.has(k));
+			if (five.length > 0) {
+				diagnostics.push({
+					kind: "spec-load",
+					severity: "info",
+					detail: `mqtt5-field-ignored: '${address}' declares MQTT 5 binding field(s) ${five
+						.sort()
+						.join(", ")}; offbook speaks MQTT 3.1.1 only, so these are not honored`,
+					source: address,
+				});
+			}
+		}
+		const rawQos = mqtt?.qos;
+		const bindingQos =
+			rawQos === 0 || rawQos === 1 || rawQos === 2 ? rawQos : undefined;
+		if (rawQos !== undefined && bindingQos === undefined) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-invalid-value: '${address}' mqtt binding qos is ${JSON.stringify(
+					rawQos,
+				)}; qos MUST be 0, 1 or 2, so this binding is ignored and the configured default applies`,
+				source: address,
+			});
+		}
+		const rawRetain = mqtt?.retain;
+		const bindingRetain =
+			typeof rawRetain === "boolean" ? rawRetain : undefined;
+		if (rawRetain !== undefined && bindingRetain === undefined) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-invalid-value: '${address}' mqtt binding retain is ${JSON.stringify(
+					rawRetain,
+				)}; retain MUST be a boolean, so this binding is ignored and the configured default applies`,
+				source: address,
+			});
+		}
+```
+
+Then update the precedence chain to consume the guarded values, replacing `mqtt?.qos` and `mqtt?.retain`:
+
+```ts
+		const override = opts.serviceConfig?.topicOverrides?.[address];
+		const qos =
+			bindingQos ?? override?.qos ?? opts.serviceConfig?.qosDefault ?? 1;
+		const retain =
+			bindingRetain ??
+			override?.retain ??
+			opts.serviceConfig?.retainDefault ??
+			false;
+```
+
+- [ ] **Step 5: Run to verify it passes**
+
+Run: `bun test src/registry/index.test.ts`
+Expected: printed failure count 0.
+
+If the JSON import fails to typecheck, confirm the resolved path first:
+
+```bash
+bun -e 'import s from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with {type:"json"}; console.log(Object.keys(s.properties).join(","))'
+```
+
+Expected: `qos,retain,messageExpiryInterval,bindingVersion`.
+
+- [ ] **Step 6: Verify all gates**
+
+Run: `bun test; echo "EXIT=$?"` then `bun run lint && bun run typecheck; echo "EXIT=$?"`
+Expected: `EXIT=0` for both. The existing `qos-retain.yaml` and `qos-overrides.yaml` precedence tests must still pass unchanged: valid bindings behave exactly as before.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts fixtures/asyncapi/v2-oldest.yaml
+git commit -m "fix(registry): guard mqtt binding values and keys (R-039)
+
+AsyncAPI 2.x maps mqtt to an empty schema, so qos: 9 and a misspelled retian
+parsed with zero errors and the bad qos reached a Channel typed 0 | 1 | 2. Guard
+the two values offbook consumes, falling through the precedence chain on a bad
+one, and report unknown keys against the official binding schema's key set plus
+MQTT-5-only fields as unhonored. Adds a 2.0.0 fixture pinning the range floor."
+```
+
+---
+
+### Task 9: Record the spec version as provenance
+
+**Files:**
+- Modify: `src/model/index.ts`, `src/ingestion/index.ts`, `src/cli/boot.ts`, `docs/specs/contracts.md`
+- Test: `src/ingestion/index.test.ts`
+
+**Interfaces:**
+- Consumes: `readSpecVersion` from Task 1.
+- Produces: optional `specVersion?: string` on `ResolvedSpec`, `LockEntry`, and `SpecInfo`; the on-disk lockfile key is `spec-version`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/ingestion/index.test.ts`, following the file's existing patterns for building a `ResolvedSpec` and asserting lockfile output:
+
+```ts
+// [utest->R-037]
+test("the lockfile records the AsyncAPI spec version beside the declared version", () => {
+	const lock = serializeLockfile({
+		lockfileVersion: 1,
+		environment: "default",
+		resolutionMode: "branch",
+		generatedAt: "2026-07-30T00:00:00.000Z",
+		services: {
+			svc: {
+				requestedVersion: "1.0.0",
+				resolutionStrategy: "branch",
+				resolvedRef: "main",
+				resolvedSha: "0".repeat(40),
+				specPath: "asyncapi.yaml",
+				declaredVersion: "4.2.0",
+				specVersion: "3.1.0",
+				contentHash: "sha256:abc",
+				fetchedAt: "2026-07-30T00:00:00.000Z",
+			},
+		},
+	});
+	expect(lock).toContain("spec-version: 3.1.0");
+	expect(lock).toContain("declared-version: 4.2.0");
+});
+
+// [utest->R-037]
+test("spec-version is omitted when the asyncapi field is unreadable", () => {
+	const lock = serializeLockfile({
+		lockfileVersion: 1,
+		environment: "default",
+		resolutionMode: "branch",
+		generatedAt: "2026-07-30T00:00:00.000Z",
+		services: {
+			svc: {
+				requestedVersion: "1.0.0",
+				resolutionStrategy: "branch",
+				resolvedRef: "main",
+				resolvedSha: "0".repeat(40),
+				specPath: "asyncapi.yaml",
+				contentHash: "sha256:abc",
+				fetchedAt: "2026-07-30T00:00:00.000Z",
+			},
+		},
+	});
+	expect(lock).not.toContain("spec-version");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test src/ingestion/index.test.ts`
+Expected: FAIL on the missing `spec-version` line, and a typecheck complaint that `specVersion` is not in `LockEntry`.
+
+- [ ] **Step 3: Add the field to the model**
+
+In `src/model/index.ts`, add to `ResolvedSpec` after `declaredVersion`:
+
+```ts
+	specVersion?: string; // the `asyncapi` version — shallow parser-free read (G12); best-effort
+```
+
+to `LockEntry` after `declaredVersion`:
+
+```ts
+	specVersion?: string; // the `asyncapi` version of the fetched spec
+```
+
+and to `SpecInfo` after `declaredVersion`:
+
+```ts
+	specVersion?: string; // the `asyncapi` version — which spec major this service is on
+```
+
+- [ ] **Step 4: Populate it through ingestion**
+
+In `src/ingestion/index.ts`, add the import:
+
+```ts
+import { readSpecVersion } from "#src/model/spec-version.ts";
+```
+
+In the resolver's returned `ResolvedSpec` (around line 157, beside `declaredVersion: readDeclaredVersion(content)`):
+
+```ts
+				specVersion: readSpecVersion(content),
+```
+
+In `toLockEntry` (around line 192, beside `declaredVersion: resolved.declaredVersion`):
+
+```ts
+		specVersion: resolved.specVersion,
+```
+
+In `serializeLockfile` (around line 215), after the `declared-version` block, keeping the same omit-when-absent shape:
+
+```ts
+					...(e.specVersion !== undefined
+						? { "spec-version": e.specVersion }
+						: {}),
+```
+
+- [ ] **Step 5: Carry it onto SpecInfo**
+
+In `src/cli/boot.ts`, in the `infos.push({ … })` call (around line 75), add beside `declaredVersion`:
+
+```ts
+				specVersion: spec.specVersion,
+```
+
+- [ ] **Step 6: Run to verify it passes**
+
+Run: `bun test src/ingestion/index.test.ts`
+Expected: printed failure count 0.
+
+Run: `bun test; echo "EXIT=$?"` then `bun run typecheck; echo "EXIT=$?"`
+Expected: `EXIT=0` for both.
+
+- [ ] **Step 7: Document it in the canonical contract**
+
+In `docs/specs/contracts.md`, add `spec-version` to the `specs.lock` per-service key list in §6 (beside `declared-version`, marked optional and best-effort) and `specVersion?: string` to the `SpecInfo` interface in §5. Note that unlike `requestedVersion`, `spec-version` is the AsyncAPI document version, not the service's own `info.version`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/model/index.ts src/ingestion/index.ts src/cli/boot.ts src/ingestion/index.test.ts docs/specs/contracts.md
+git commit -m "feat(ingestion): record the AsyncAPI spec version as provenance (R-037)
+
+Read the asyncapi field in the same parser-free pass as info.version and record
+it as spec-version in specs.lock and on SpecInfo, so GET /v1/specs answers which
+spec major each service is on. doctor deliberately does not report it: its spec
+checks are network-free while the spec lives in a remote repo."
+```
+
+---
+
+### Task 10: Close out the gates and the adopter docs
+
+**Files:**
+- Modify: `REQUIREMENTS.md`, `fixtures/asyncapi/README.md`, `README.md`, `docs/guides/wiring-your-service.md`, `test/gate-validation.test.ts` (confirm the real filename from R-028's TEST trace)
+- Test: the R-028 gate file
+
+**Interfaces:**
+- Consumes: everything above.
+- Produces: `R-037`, `R-038`, `R-039` at `STATUS: tested` with `IMPL`/`TEST` traces.
+
+- [ ] **Step 1: Find the R-028 gate file**
+
+Run: `grep -n -A6 "UID\*\*: R-028" REQUIREMENTS.md`
+Expected: prints the `TEST` trace naming the gate file. Use that exact path in the next step.
+
+- [ ] **Step 2: Extend the R-028 gate over the new fixtures**
+
+Read the gate file first and follow its existing structure. It drives fixtures through the composed stack and asserts delivery, the violation log, and wire-level qos/retain. Add `multi-format.yaml` and `v2-oldest.yaml` to the fixture list it iterates, and add one assertion per new fixture proving a known-bad payload is REJECTED end to end (not merely at the unit level), because the false-negative class is what this gate exists to catch.
+
+If the gate hardcodes fixture names in an array, extend that array. If it hardcodes per-fixture expectations, add matching entries. Do not weaken any existing assertion to accommodate the new fixtures.
+
+- [ ] **Step 3: Run the gate**
+
+Run: `bun test; echo "EXIT=$?"`
+Expected: `EXIT=0`.
+
+- [ ] **Step 4: Flip the three requirements to tested**
+
+In `REQUIREMENTS.md`, add the traces and change each `STATUS` from `specified` to `tested`:
+
+For `R-037`:
+```markdown
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/model/spec-version.ts, src/registry/index.ts, src/ingestion/index.ts
+**TEST**: src/model/spec-version.test.ts, src/registry/index.test.ts, src/ingestion/index.test.ts
+```
+
+For `R-038`:
+```markdown
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/registry/index.ts
+**TEST**: src/registry/index.test.ts
+```
+
+For `R-039`:
+```markdown
+**STATUS**: tested
+**COVERS**: docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
+**IMPL**: src/registry/index.ts
+**TEST**: src/registry/index.test.ts
+```
+
+- [ ] **Step 5: Verify the doc gate accepts the traces**
+
+Run: `bun scripts/check-docs.ts; echo "EXIT=$?"`
+Expected: `EXIT=0`. The checker verifies arrow tags in both directions, so every file named in a `TEST` trace must carry at least one `// [utest->R-###]` for that id, and no tag may reference a missing requirement. If it reports a dangling or missing tag, fix the tag rather than the trace.
+
+- [ ] **Step 5b: Finish the D-005 decision sweep**
+
+Task 3 reversed the canonical dialect statement in `contracts.md` and closed D-005 as superseded, but two files still assert the old story and now **contradict the canonical contract**. Under this repo's conflict rule, contracts wins and these must be fixed. Both were found during Task 3 execution and neither is listed in any other step.
+
+In `fixtures/asyncapi/README.md`, the `external-ref.yaml` row still reads "a `$ref` **sibling keyword** (`minLength`) that a 2020-12 dialect *should* honor but the draft-07 parser drops: a **known limitation (D-005)**, pinned by a tripwire test, deferred to a 2020-12 schema-parser spike". Reword to match the shipped behaviour: the sibling is not enforced because draft-07 is the dialect both majors declare and offbook validates under, which is correct rather than a limitation, pinned by a tripwire so a future dialect change is loud (D-018 supersedes D-005).
+
+In `REQUIREMENTS.md`, R-004's prose still says "the 2020-12 `$ref`-sibling edge is carved out to D-005, pinned by a tripwire test". Reword to reference the draft-07 dialect and D-018. Do not change R-004's `STATUS` or traces.
+
+Grep for any remaining stale claims before moving on:
+
+```bash
+grep -rn "D-005\|2020-12" --include="*.md" --include="*.yaml" --include="*.ts" . | grep -v node_modules | grep -v "docs/superpowers/" | grep -v coverage/
+```
+
+Expected: every surviving mention is either inside D-005's own ledger entry (history, which stays intact), inside D-018's supersede note, or a deliberate statement that 2020-12 is **not** what offbook validates under. Anything else is an unswept claim.
+
+- [ ] **Step 6: Update the fixtures README**
+
+In `fixtures/asyncapi/README.md`, add two rows to the table:
+
+```markdown
+| `multi-format.yaml` | 3.1.0 | The explicit Multi Format Schema Object payload (`{schemaFormat, schema}`) on **both** a `send` and a `receive` operation — the wrapper the parser returns verbatim, which made the validator accept everything (D-018). Also the newest-supported-major acceptance fixture |
+| `v2-oldest.yaml` | 2.0.0 | The **floor** of the supported range: `publish`/`subscribe` inversion plus a 2.x mqtt operation binding at `qos: 2` (2.x validates bindings not at all, so offbook checks them itself) |
+```
+
+And add a supported-version statement under the direction-mapping section:
+
+```markdown
+## Supported AsyncAPI versions
+offbook supports **2.0.0 through 2.6.0, 3.0.0, and 3.1.0** (D-018); 3.1.0 is the recommended authoring target. AsyncAPI 1.x is refused: convert it first. Fixtures should stay within this range, and the range itself is pinned by a test over `SUPPORTED_SPEC_VERSIONS`.
+```
+
+- [ ] **Step 7: State the range for adopters**
+
+In `README.md`, near the prerequisites list that mentions git access to the spec repos, add:
+
+```markdown
+- AsyncAPI specs at **2.0.0-2.6.0, 3.0.0, or 3.1.0** (3.1.0 recommended). AsyncAPI 1.x is not supported: convert it with `asyncapi convert` first.
+```
+
+In `docs/guides/wiring-your-service.md`, add a short subsection covering the same range plus the perspective caveat, which matters more on 2.x than anything else in this plan:
+
+```markdown
+## AsyncAPI versions
+
+offbook reads AsyncAPI **2.0.0 through 2.6.0, 3.0.0, and 3.1.0**. 3.1.0 is the recommended target for new specs. A 1.x spec is refused with a message telling you to convert it.
+
+### If your spec is 2.x, check its perspective
+
+AsyncAPI 2.x names operations from the point of view of your service's *counterparties*, which is the opposite of what most people assume:
+
+- `subscribe` means **your service publishes** the message, so offbook treats it as `toClient` and mocks it for your browser app to receive.
+- `publish` means **your service consumes** the message, so offbook treats it as `fromClient` and validates what your browser app sends.
+
+That is what the specification says, and it is what the official converter does. But the convention is widely misread, and some generators grew flags (`view=provider`, `inverseOperations=true`) for specs authored the other way around. If every mocked channel points the wrong way, your spec was probably written from the client's perspective. No tool can detect this from the document, so it needs a human read.
+```
+
+- [ ] **Step 8: Run the complete gate set**
+
+Run each and confirm `EXIT=0`:
+
+```bash
+bun scripts/check-docs.ts; echo "EXIT=$?"
+bun run lint; echo "EXIT=$?"
+bun run typecheck; echo "EXIT=$?"
+bun run demo-app:build; echo "EXIT=$?"
+bun test; echo "EXIT=$?"
+```
+
+Expected: `EXIT=0` for all five. This is the same set CI runs.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add REQUIREMENTS.md fixtures/asyncapi/README.md README.md docs/guides/wiring-your-service.md test/
+git commit -m "docs: declare the AsyncAPI support range and close R-037..R-039
+
+Extend the R-028 validation gate over multi-format.yaml and v2-oldest.yaml so
+the false-negative class is covered by a v1 gate, flip the three requirements to
+tested with traces, and state the supported range for adopters. The wiring guide
+gains the 2.x perspective caveat: a spec authored from the client's point of view
+loads with every direction inverted and no tool can detect it."
+```
+
+---
+
+## Self-Review
+
+**Spec coverage.** Every section of the design maps to a task: the support contract and preflight to Task 1; `spec-version` provenance to Task 9; the payload boundary's four parts to Tasks 2 (unwrap), 3 (dialect), 5 (mismatch diagnostic), 6 (compile containment), and 7 (multi-message); binding integrity's four parts to Tasks 4 (channel binding) and 8 (value guard, key set, MQTT 5); fixtures to Tasks 2, 3, and 8; tests and the R-028 extension to Task 10; doc and provenance changes to Tasks 1, 3, 4, 9, and 10. The two spec claims that did not survive planning are called out under **Deviations** rather than silently dropped.
+
+**Placeholder scan.** No TBD or TODO. Every code step carries the actual code. Two steps deliberately require reading an existing file before editing (the R-028 gate in Task 10, and `composition.yaml` placement in Task 3) because their internal structure was not read during planning; both give the exact command to discover what is needed and the exact content to add. The `contracts.md` edits describe the replacement text and how to locate the passages, since that file's full prose was not read.
+
+**Type consistency.** `extractPayloadSchema` is introduced in Task 2 and reused in Tasks 3 and 7 under that name. `DRAFT_07` is introduced in Task 3 and reused in Tasks 6 and 7. The `diagnostics` array is introduced in Task 4 and pushed to in Tasks 5, 6, and 8. `bindingQos`/`bindingRetain` replace `mqtt?.qos`/`mqtt?.retain` in the same task that introduces them (Task 8). `specVersion` is the camelCase model field and `spec-version` the kebab-case on-disk key throughout, matching the existing §6 convention. `readSpecVersion`, `isSupportedSpecVersion`, and `SUPPORTED_SPEC_VERSIONS` keep the same names from Task 1 through Tasks 9 and 10.
+
+**Ordering constraint.** Task 1 must land before Task 2, because `multi-format.yaml` declares 3.1.0 and the preflight gate must already accept it. Task 4 must land before Tasks 5, 6, and 8, which push into the diagnostics array it introduces.
+
+**Parse-verified during planning.** Every spec literal in this plan was run through `@asyncapi/parser` 3.6.0 before the plan was committed, because v2 and v3 document structure differs enough that a hand-written fixture is easy to get subtly wrong. Confirmed: both new fixtures parse with zero error-severity diagnostics; `multi-format.yaml` yields two channels (`send` plus `receive`) whose payload JSON really is the `{schemaFormat, schema}` wrapper, so the fixture does reproduce the defect it pins; `v2-oldest.yaml` yields `subscribe` plus `publish` with its mqtt binding read as `{"qos":2,"retain":true}`; and the inline specs for Tasks 4, 5, 6, and 8 all parse. The one shape that did **not** survive verification was Task 6's original `minLength: not-a-number`, which the parser rejects outright; it was replaced with the invalid-regex `pattern: '['` case, and Task 6 carries a warning not to substitute another shape without re-checking.
diff --git a/docs/superpowers/plans/2026-08-01-asyncapi-version-gate-hardening.md b/docs/superpowers/plans/2026-08-01-asyncapi-version-gate-hardening.md
new file mode 100644
index 0000000..c407c15
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-01-asyncapi-version-gate-hardening.md
@@ -0,0 +1,764 @@
+# AsyncAPI Version Gate Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix three defects in the shipped R-037/R-039 ingestion path: a version preflight that swallows every parse failure and gives wrong advice, an undeclared `@asyncapi/specs` import, and a false "unknown key" warning on spec-legal vendor extensions.
+
+**Architecture:** The preflight stops guessing. It refuses only a version it positively read and positively recognizes as untested; anything else falls through to `@asyncapi/parser`, whose diagnostics for malformed YAML and non-AsyncAPI documents are already accurate. `@asyncapi/specs` becomes a devDependency, so the mqtt binding key set becomes a hand-authored constant in `registry/` and a new `test/upstream-drift.test.ts` gate keeps that constant, the supported-version set, and the devDependency boundary honest.
+
+**Tech Stack:** Bun 1.3.14, TypeScript (strict), `bun test`, Biome 1.9, `@asyncapi/parser` 3.6.0, `@asyncapi/specs` 6.11.1.
+
+**Spec:** `docs/superpowers/specs/2026-08-01-asyncapi-version-gate-hardening-design.md`. **Decision:** D-019 (amends D-018). **Requirements:** R-037, R-039.
+
+## Global Constraints
+
+- **Do not commit unless a step says to.** Every task ends with its own commit.
+- **No `Co-Authored-By` or AI-attribution trailer** on any commit in this repo.
+- **Never run `git config user.*`.** Git identity is the user's to set.
+- **Verify by exit code, not by printed counts,** with one documented exception: `bun test <single-file>` can exit 1 with zero failures, because bunfig.toml's per-file coverage floor judges partially-imported files. So during a TDD loop, read the `N pass / M fail` line from a single-file run; the task's final gate is always a **full `bun test`** run judged by its exit code.
+- **Full gate set** (each must exit 0): `bun scripts/check-docs.ts`, `bun run lint`, `bun run typecheck`, `bun run demo-app:build`, `bun test`.
+- **Import style:** upward reaches use `#src/…`, same-directory and downward stay relative, always with explicit `.ts` extensions. Enforced by `test/import-style.test.ts`.
+- **Arrow tags are required** on tests that satisfy a requirement: `// [utest->R-###]`, `// [itest->R-###]`, or `// [stest->R-###]`. `bun scripts/check-docs.ts` verifies them in both directions (missing and dangling), so a new test file must be listed in that requirement's `TEST:` line.
+- **After writing any new file, run `bunx biome check --write <that file>`** before linting the repo. Biome's formatter has opinions about line wrapping that are tedious to guess.
+- **Supported version set (verbatim):** `2.0.0`, `2.1.0`, `2.2.0`, `2.3.0`, `2.4.0`, `2.5.0`, `2.6.0`, `3.0.0`, `3.1.0`.
+- **Do not touch `biome.json`.** The spec explicitly rejected a lint rule for the re-import guard: Biome 1.9's `noRestrictedImports.paths` matches whole module specifiers, so a bare `@asyncapi/specs` entry does not flag `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` (verified both ways). Task 3's source-text check replaces it.
+
+## File Structure
+
+| File | Responsibility | Task |
+|---|---|---|
+| `src/registry/index.ts` | Modify: preflight firing rule + message; hand-authored binding constants; vendor-extension allowance | 1, 2 |
+| `src/registry/index.test.ts` | Modify: 4 new cases, 2 rewritten | 1, 2 |
+| `package.json` | Modify: add `@asyncapi/specs` devDependency | 2 |
+| `bun.lock` | Regenerated by `bun install` | 2 |
+| `test/upstream-drift.test.ts` | Create: version-set drift, binding-key drift, devDependency boundary | 3 |
+| `REQUIREMENTS.md` | Modify: R-037/R-039 `TEST:` lines (3, so that task's commit is green), then their bodies (4) | 3, 4 |
+| `DECISIONS.md` | Modify: append D-019 | 4 |
+| `docs/specs/build-plan.md` | Modify: §1 AsyncAPI row note | 4 |
+
+**Out of scope** (review findings 4-13, each independent): the untested compose wiring, the mis-attributed `$ref`-sibling tripwire, the duplicated `binding-on-channel` diagnostic, the `dialect-mismatch` property-name false positive, the `schema: false` wrapper hole, and the nits. Do not fix them here.
+
+---
+
+### Task 1: The version gate refuses only what it recognizes
+
+**Files:**
+- Modify: `src/registry/index.ts:136-152`
+- Test: `src/registry/index.test.ts` (3 new tests, 2 rewritten)
+
+**Interfaces:**
+- Consumes: `readSpecVersion(specText: string): string | undefined` and `isSupportedSpecVersion(v: string | undefined): boolean` from `#src/model/spec-version.ts`, plus `SUPPORTED_SPEC_VERSIONS`. **None of these three change signature.**
+- Produces: `buildRegistry` throws `unsupported AsyncAPI version "<v>" in service '<name>': offbook supports <all nine, comma-joined>. Convert the spec first: \`asyncapi convert <file> --target-version 3.1.0\`` for a readable-but-untested version, and defers to the existing `failed to parse spec: <parser diagnostics>` throw for everything else.
+
+- [ ] **Step 1: Write the three new tests**
+
+Two of these fail now and pass after Step 4. The third, the unquoted-`2.6` case, **passes both before and after**: it is a characterization test pinning behavior the refactor must preserve, and it is what stops a naive "just delete the preflight" reading of this task. Keep it.
+
+Append to `src/registry/index.test.ts` (after the existing `refuses a 1.x spec…` test, which Step 2 rewrites):
+
+```ts
+// [utest->R-037]
+test("a malformed spec surfaces the parser's own diagnostics, not a version error", async () => {
+	// A YAML syntax error is not a version problem, and `asyncapi convert` is not
+	// its remedy. Spec-load failure is fatal and aborts `up` (design §7 Mode 1),
+	// so this message is the whole error an adopter sees (R-036, D-019).
+	const err = await buildRegistry({
+		specText: "asyncapi: 3.0.0\ninfo: {title: T\n  bad indent: ][",
+		service: "svc-a",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error);
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/failed to parse spec/);
+	expect(err.message).toMatch(/flow/); // the parser's own YAML syntax wording
+	expect(err.message).not.toMatch(/unsupported AsyncAPI version/);
+	expect(err.message).not.toMatch(/asyncapi convert/);
+});
+
+// [utest->R-037]
+test("an unquoted `asyncapi: 2.6` is refused before the parser's TypeError", async () => {
+	// `asyncapi: 2.6` is a YAML float, not a string, and the parser dies on it
+	// inside getSemver with a raw `patchWithRc.split` TypeError stack. The gate
+	// catches it first because String(2.6) is "2.6", which is not a tested
+	// version. This is why readSpecVersion normalizes with String() (D-019).
+	const err = await buildRegistry({
+		specText: "asyncapi: 2.6\ninfo: { title: T, version: 1.0.0 }\nchannels: {}",
+		service: "floaty",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error);
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/unsupported AsyncAPI version "2\.6"/);
+	expect(err.message).not.toMatch(/patchWithRc/);
+});
+
+// [utest->R-037]
+test("a version inside the old range but outside the tested set is still refused", async () => {
+	// 2.7.0 sits INSIDE "2.0.0 through 3.1.0" while being untested, which is
+	// exactly why the message names the set instead of a range (D-019).
+	const err = await buildRegistry({
+		specText:
+			"asyncapi: '2.7.0'\ninfo: { title: T, version: 1.0.0 }\nchannels: {}",
+		service: "future",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error);
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/unsupported AsyncAPI version "2\.7\.0"/);
+	expect(err.message).not.toMatch(/through/);
+});
+```
+
+- [ ] **Step 2: Rewrite the two tests whose behavior changes**
+
+In `src/registry/index.test.ts`, replace these three lines inside the existing `refuses a 1.x spec with an actionable, branded error` test (currently lines 224-226):
+
+```ts
+	// names the supported range and the remedy, not just the problem
+	await expect(attempt).rejects.toThrow(/2\.0\.0/);
+	await expect(attempt).rejects.toThrow(/asyncapi convert/);
+```
+
+with:
+
+```ts
+	// names EVERY tested version and the remedy, not just the problem. Built from
+	// the constant, so the assertion cannot drift from what the message renders.
+	for (const v of SUPPORTED_SPEC_VERSIONS) {
+		await expect(attempt).rejects.toThrow(v);
+	}
+	await expect(attempt).rejects.toThrow(/asyncapi convert/);
+```
+
+(`SUPPORTED_SPEC_VERSIONS` is already imported at the top of this test file. `toThrow(string)` is a substring match, which is what we want here.)
+
+Then replace the whole `refuses a spec with no asyncapi field` test (currently lines 229-238) with:
+
+```ts
+// [utest->R-037]
+test("a spec with no asyncapi field defers to the parser's diagnosis", async () => {
+	// Not offbook's call to make: the parser names the real problem precisely,
+	// and guessing "unsupported version" here mislabels an empty file, an HTML
+	// error page from a bad repo URL, and a wrong spec-path alike (D-019).
+	const err = await buildRegistry({
+		specText: "info: { title: T, version: 1.0.0 }",
+		service: "nover",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error);
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/failed to parse spec/);
+	expect(err.message).toMatch(/This is not an AsyncAPI document/);
+	expect(err.message).not.toMatch(/unsupported AsyncAPI version/);
+});
+```
+
+- [ ] **Step 3: Run the tests to verify they fail**
+
+Run: `bun test src/registry/index.test.ts 2>&1 | tail -30`
+
+Expected: `4 fail`, and they must be these four:
+
+| failing test | why it fails now |
+|---|---|
+| `a malformed spec surfaces the parser's own diagnostics` | the preflight throws `unsupported AsyncAPI version (no \`asyncapi\` field found)` before the parser ever runs |
+| `a spec with no asyncapi field defers to the parser's diagnosis` | same throw |
+| `a version inside the old range but outside the tested set is still refused` | the message still renders `2.0.0 through 3.1.0`, so the `not.toMatch(/through/)` assertion fails |
+| `refuses a 1.x spec with an actionable, branded error` | the range rendering contains `2.0.0` and `3.1.0` but not `2.1.0` … `3.0.0`, so the new loop fails |
+
+The unquoted-`2.6` test passes already, as noted in Step 1. Ignore the process exit code here (coverage floor).
+
+- [ ] **Step 4: Change the preflight**
+
+In `src/registry/index.ts`, replace lines 136-152 exactly:
+
+```ts
+	// R-037 preflight: check the declared version BEFORE handing the document to
+	// the parser. The parser's own gate is derived from @asyncapi/specs at
+	// install time, so an unsupported-but-present version can pass it and then
+	// fail deep in the Spectral ruleset with an opaque "Error running Nimma".
+	// Offbook's supported set is a promise it tests, so it is checked here (D-018).
+	const specVersion = readSpecVersion(opts.specText);
+	if (!isSupportedSpecVersion(specVersion)) {
+		throw new Error(
+			`unsupported AsyncAPI version ${
+				specVersion === undefined
+					? "(no `asyncapi` field found)"
+					: `"${specVersion}"`
+			} in service '${opts.service}': offbook supports ${SUPPORTED_SPEC_VERSIONS[0]} through ${
+				SUPPORTED_SPEC_VERSIONS[SUPPORTED_SPEC_VERSIONS.length - 1]
+			}. Convert the spec first: \`asyncapi convert <file> --target-version 3.1.0\``,
+		);
+	}
+```
+
+with:
+
+```ts
+	// R-037 preflight: check the declared version BEFORE handing the document to
+	// the parser. The parser's own gate is derived from @asyncapi/specs at
+	// install time, so an unsupported-but-present version can pass it and then
+	// fail deep in the Spectral ruleset with an opaque "Error running Nimma"
+	// (D-018) — or, for an unquoted `asyncapi: 2.6`, with a raw TypeError stack
+	// out of getSemver.
+	//
+	// Fires ONLY on a version this read positively resolved. An unreadable or
+	// absent `asyncapi` field is not offbook's call to make: the parser's own
+	// diagnostics distinguish a YAML syntax error from a non-AsyncAPI document,
+	// and guessing "unsupported version" mislabelled both, along with the empty
+	// file and the fetched HTML error page (D-019). The message names the tested
+	// set rather than a range, because a version can sit inside 2.0.0-3.1.0 and
+	// still be untested.
+	const specVersion = readSpecVersion(opts.specText);
+	if (specVersion !== undefined && !isSupportedSpecVersion(specVersion)) {
+		throw new Error(
+			`unsupported AsyncAPI version "${specVersion}" in service '${opts.service}': offbook supports ${SUPPORTED_SPEC_VERSIONS.join(
+				", ",
+			)}. Convert the spec first: \`asyncapi convert <file> --target-version 3.1.0\``,
+		);
+	}
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `bun test src/registry/index.test.ts 2>&1 | tail -20`
+
+Expected: `0 fail`.
+
+- [ ] **Step 6: Confirm the guard is load-bearing (mutation check)**
+
+Temporarily delete `specVersion !== undefined && ` from the `if` you just wrote, then run:
+
+Run: `bun test src/registry/index.test.ts 2>&1 | grep -E "^ *[0-9]+ (pass|fail)"`
+
+Expected: `2 fail` (`a malformed spec surfaces the parser's own diagnostics` and `a spec with no asyncapi field defers to the parser's diagnosis`). If either still passes, the assertion is not testing what it claims: fix the test, not the count.
+
+Restore the `specVersion !== undefined && ` guard and re-run to confirm `0 fail`.
+
+- [ ] **Step 7: Run the full gate set**
+
+```sh
+bun run lint && bun run typecheck && bun test
+```
+
+Expected: exit 0. `bun test` should report `426 pass, 0 fail` (423 before, plus 3 net new).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/registry/index.ts src/registry/index.test.ts
+git commit -m "fix(registry): refuse only versions the preflight recognizes (R-037)
+
+The preflight ran before parser.parse() and treated readSpecVersion's
+undefined as 'unsupported version', so malformed YAML, an empty file,
+and a fetched HTML error page all died with a version error advising
+\`asyncapi convert\`, which is the wrong remedy for all three. Spec-load
+failure aborts \`up\` in the foreground, so that message was the whole
+error an adopter saw (R-036).
+
+It now fires only on a version it positively read and positively
+recognizes as untested; everything else falls through to the parser,
+whose diagnostics already distinguish a YAML syntax error from a
+non-AsyncAPI document. An unquoted \`asyncapi: 2.6\` is still caught
+here, ahead of the parser's raw getSemver TypeError.
+
+The message names the tested set instead of '2.0.0 through 3.1.0',
+which would have told a 2.7.0 user they were supported while refusing
+them."
+```
+
+---
+
+### Task 2: `@asyncapi/specs` becomes a devDependency, binding constants become hand-authored
+
+**Files:**
+- Modify: `package.json` (devDependencies)
+- Modify: `src/registry/index.ts:1-4` (drop import), `:85-97` (constants), `:244-246` (filter)
+- Modify: `bun.lock` (regenerated)
+- Test: `src/registry/index.test.ts` (1 new test)
+
+**Interfaces:**
+- Produces: `src/registry/index.ts` exports two new constants that Task 3's gate imports:
+  - `export const MQTT_OPERATION_KEYS: Set<string>`
+  - `export const MQTT_EXTENSION_KEY: RegExp`
+- Produces: no file under `src/` imports `@asyncapi/specs` at any subpath.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/registry/index.test.ts`:
+
+```ts
+// [utest->R-039]
+test("a vendor extension key on an mqtt binding is legal, not an unknown key", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/ext, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o:
+    action: send
+    channel: { $ref: '#/channels/c' }
+    bindings: { mqtt: { qos: 2, x-vendor-thing: true } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	// the official binding schema permits ^x-[\w\d\.\x2d_]+$ via patternProperties,
+	// which the derived key set ignored because it read only `properties` (D-019)
+	expect(
+		reg
+			.diagnostics()
+			.filter((d) => d.detail.startsWith("binding-unknown-key:")),
+	).toEqual([]);
+	// and the legal fields on the same binding still take effect: qos 2 differs
+	// from the global default of 1, so this assertion is not vacuous
+	expect(reg.match("t/ext")?.channel.qos).toBe(2);
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `bun test src/registry/index.test.ts -t "vendor extension" 2>&1 | tail -20`
+
+Expected: `1 fail`, with the received value being one `binding-unknown-key` diagnostic reading `… has unknown key(s) x-vendor-thing; the mqtt binding defines bindingVersion, messageExpiryInterval, qos, retain`.
+
+- [ ] **Step 3: Declare the devDependency**
+
+In `package.json`, add `@asyncapi/specs` as the first entry of `devDependencies` (they are alphabetized):
+
+```json
+	"devDependencies": {
+		"@asyncapi/specs": "^6.11.1",
+		"@biomejs/biome": "^1.9.0",
+```
+
+Then run: `bun install`
+
+Expected: `bun.lock` gains `@asyncapi/specs` under the root package's `devDependencies`; the resolved version stays `6.11.1` (it was already in the lock as a transitive of `@asyncapi/parser`). Confirm nothing else moved:
+
+Run: `git diff --stat bun.lock package.json`
+
+Expected: only those two files, and `bun.lock` shows a small addition. If `bun.lock` shows unrelated version bumps, stop and report: the lockfile should not churn.
+
+- [ ] **Step 4: Drop the runtime import and hand-author the constants**
+
+In `src/registry/index.ts`, delete lines 2-4 entirely:
+
+```ts
+import mqttOperationBinding from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with {
+	type: "json",
+};
+```
+
+Then replace the `MQTT_OPERATION_KEYS` block (currently lines 85-97):
+
+```ts
+// The legal key set comes from the OFFICIAL binding schema rather than a
+// hardcoded list, so it tracks upstream. Only `properties` is read: the schema
+// cannot be compiled standalone (it $refs
+// http://asyncapi.com/definitions/3.0.0/schema.json, resolvable only inside the
+// bundled spec schema), and offbook consumes just qos and retain anyway.
+// Validating against 0.2.0 is permissive-correct: its property set is a
+// superset of 0.1.0's.
+const MQTT_OPERATION_KEYS = new Set(
+	Object.keys(
+		(mqttOperationBinding as { properties: Record<string, unknown> })
+			.properties,
+	),
+);
+```
+
+with:
+
+```ts
+// The mqtt OPERATION binding's legal keys, transcribed from @asyncapi/specs'
+// bindings/mqtt/0.2.0/operation.json. Hand-authored and drift-tested rather than
+// derived at runtime, for the reason D-018 gave for SUPPORTED_SPEC_VERSIONS: a
+// value being present upstream is not the same as offbook having tested it.
+// Keeping it a constant is also what lets @asyncapi/specs be a devDependency
+// (D-019) instead of an undeclared transitive of @asyncapi/parser, resolved only
+// by flat hoisting. Validating against 0.2.0 is permissive-correct: its property
+// set is a superset of 0.1.0's. Exported for test/upstream-drift.test.ts, which
+// pins both halves against the installed schema.
+export const MQTT_OPERATION_KEYS = new Set([
+	"bindingVersion",
+	"messageExpiryInterval",
+	"qos",
+	"retain",
+]);
+
+// The same schema permits vendor extensions via `patternProperties`. Transcribed
+// character-for-character from that key, so the drift test compares source
+// strings rather than approximating the intent. Reading only `properties` meant
+// a spec-legal `x-vendor-thing` was reported as an unknown key (D-019).
+export const MQTT_EXTENSION_KEY = /^x-[\w\d\.\x2d_]+$/;
+```
+
+- [ ] **Step 5: Honor the extension pattern in the unknown-key filter**
+
+In `src/registry/index.ts` (currently lines 244-246), replace:
+
+```ts
+			const unknownKeys = Object.keys(mqtt).filter(
+				(k) => !MQTT_OPERATION_KEYS.has(k),
+			);
+```
+
+with:
+
+```ts
+			const unknownKeys = Object.keys(mqtt).filter(
+				(k) => !MQTT_OPERATION_KEYS.has(k) && !MQTT_EXTENSION_KEY.test(k),
+			);
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `bun test src/registry/index.test.ts 2>&1 | tail -20`
+
+Expected: `0 fail`.
+
+- [ ] **Step 7: Confirm the extension allowance is load-bearing (mutation check)**
+
+Temporarily delete ` && !MQTT_EXTENSION_KEY.test(k)` from the filter, then run:
+
+Run: `bun test src/registry/index.test.ts -t "vendor extension" 2>&1 | grep -E "^ *[0-9]+ (pass|fail)"`
+
+Expected: `1 fail`. Restore the clause and re-run to confirm `0 fail`.
+
+- [ ] **Step 8: Run the full gate set**
+
+```sh
+bun run lint && bun run typecheck && bun test
+```
+
+Expected: exit 0, `427 pass, 0 fail`.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add package.json bun.lock src/registry/index.ts src/registry/index.test.ts
+git commit -m "fix(registry): make @asyncapi/specs a devDependency (R-039)
+
+src/registry/ imported @asyncapi/specs/bindings/mqtt/0.2.0/operation.json
+to derive the legal mqtt operation-binding key set, but that package is a
+transitive dependency of @asyncapi/parser, not a declared one, so the
+import resolved only through flat hoisting. A parser upgrade that bumps
+or drops the dep, or an install under a non-hoisting layout, breaks the
+build. The subpath is also an unversioned internal file: the package
+publishes no exports map.
+
+The key set is now a hand-authored constant, extending to bindings the
+reasoning D-018 applied to SUPPORTED_SPEC_VERSIONS, with the package
+demoted to a devDependency for the drift gate that follows.
+
+Transcribing the schema by hand also surfaced what deriving it hid: only
+\`properties\` was being read, so the schema's patternProperties allowance
+for ^x- vendor extensions was dropped and a spec-legal x-vendor-thing was
+reported as an unknown key."
+```
+
+---
+
+### Task 3: The upstream-drift gate
+
+**Files:**
+- Create: `test/upstream-drift.test.ts`
+
+**Interfaces:**
+- Consumes: `SUPPORTED_SPEC_VERSIONS` from `#src/model/spec-version.ts`; `MQTT_OPERATION_KEYS` and `MQTT_EXTENSION_KEY` from `#src/registry/index.ts` (both exported in Task 2).
+- Produces: nothing. This is a terminal gate.
+
+- [ ] **Step 1: Write the gate**
+
+Create `test/upstream-drift.test.ts` with exactly this content:
+
+```ts
+// R-037 / R-039 — the upstream-drift gate. offbook hand-authors two constants
+// that mirror @asyncapi/specs (the supported version set and the mqtt operation
+// binding's key contract) rather than deriving them at runtime, because a value
+// being present upstream is not the same as offbook having tested it (D-018,
+// D-019). Hand-authored constants go stale silently, so this gate makes the
+// drift loud at the dependency bump, which is the moment someone can act on it.
+// @asyncapi/specs is a devDependency: this file is the ONLY place it may be
+// imported, which the third check enforces.
+// [stest->R-037]
+// [stest->R-039]
+import { expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import specs from "@asyncapi/specs";
+import mqttOperationBinding from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with {
+	type: "json",
+};
+import { SUPPORTED_SPEC_VERSIONS } from "#src/model/spec-version.ts";
+import {
+	MQTT_EXTENSION_KEY,
+	MQTT_OPERATION_KEYS,
+} from "#src/registry/index.ts";
+
+function walk(dir: string): string[] {
+	return readdirSync(dir).flatMap((name) => {
+		const p = join(dir, name);
+		return statSync(p).isDirectory() ? walk(p) : [p];
+	});
+}
+
+test("SUPPORTED_SPEC_VERSIONS matches the versions @asyncapi/specs exposes", () => {
+	// Exact equality, no filtering: the 2.0.0-rc1/rc2 schemas exist on disk but
+	// are excluded from the export map, so `schemas` is exactly the release set.
+	//
+	// Red here means a parser bump changed the available versions. The fix is to
+	// verify the new version against the real parser and then add it to the
+	// constant — NOT to derive the constant from this. Parser 3.4.0 shipped the
+	// 3.1.0 schema and still died inside its own ruleset (D-018), which this
+	// check cannot see.
+	expect([...SUPPORTED_SPEC_VERSIONS]).toEqual(
+		Object.keys((specs as { schemas: Record<string, unknown> }).schemas),
+	);
+});
+
+test("the mqtt operation binding constants match the official schema", () => {
+	const schema = mqttOperationBinding as {
+		properties: Record<string, unknown>;
+		patternProperties: Record<string, unknown>;
+	};
+	expect([...MQTT_OPERATION_KEYS].sort()).toEqual(
+		Object.keys(schema.properties).sort(),
+	);
+	// transcribed character-for-character, so the source strings compare directly
+	expect(Object.keys(schema.patternProperties)).toEqual([
+		MQTT_EXTENSION_KEY.source,
+	]);
+});
+
+test("@asyncapi/specs stays a devDependency: nothing under src/ imports it", () => {
+	// Biome's noRestrictedImports matches whole module specifiers, so it cannot
+	// express "this package at any subpath", and the realistic regression is a
+	// deep JSON import like the one this gate replaced (D-019). Same idiom as
+	// test/transport-isolation.test.ts and ingestion's G12 guard: match the
+	// import edge, not mentions of the name in prose comments.
+	const offenders = walk("src")
+		.filter((p) => p.endsWith(".ts"))
+		.filter((p) =>
+			/from\s+["']@asyncapi\/specs(\/[^"']*)?["']/.test(
+				readFileSync(p, "utf8"),
+			),
+		);
+	expect(offenders).toEqual([]);
+});
+```
+
+- [ ] **Step 2: Format and run it**
+
+```sh
+bunx biome check --write test/upstream-drift.test.ts
+bun test test/upstream-drift.test.ts 2>&1 | tail -20
+```
+
+Expected: `3 pass, 0 fail`. All three describe invariants Tasks 1 and 2 already established, so they pass on arrival. Step 3 is what proves they are worth having.
+
+- [ ] **Step 3: Confirm all three checks are load-bearing (mutation check)**
+
+Perturb one thing at a time, run `bun test test/upstream-drift.test.ts 2>&1 | grep -E "^ *[0-9]+ (pass|fail)"`, and restore before moving to the next:
+
+1. Add `"2.7.0"` to `SUPPORTED_SPEC_VERSIONS` in `src/model/spec-version.ts` → expect `1 fail`.
+2. Delete `"bindingVersion"` from `MQTT_OPERATION_KEYS` in `src/registry/index.ts` → expect `1 fail`.
+3. Change `MQTT_EXTENSION_KEY` to `/^x-.+$/` → expect `1 fail` (the `patternProperties` source comparison).
+4. Re-add `import mqttOperationBinding from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with { type: "json" };` to the top of `src/registry/index.ts` → expect `1 fail`, with `["src/registry/index.ts"]` as the received value.
+
+After the fourth, confirm `src/registry/index.ts` is byte-identical to its committed state:
+
+Run: `git diff --stat src/ && bun test test/upstream-drift.test.ts 2>&1 | grep -E "^ *[0-9]+ (pass|fail)"`
+
+Expected: no diff output, and `3 pass`.
+
+- [ ] **Step 4: Register the new file against both requirements**
+
+The gate carries `[stest->R-037]` and `[stest->R-039]`, and `bun scripts/check-docs.ts` verifies arrow tags in both directions, so it fails with a dangling-tag error until both requirements list the file. Fix that now, in this task, so the commit lands green.
+
+In `REQUIREMENTS.md`, in the `R-037` block, replace the `**TEST**:` line:
+
+```
+**TEST**: src/model/spec-version.test.ts, src/registry/index.test.ts, src/ingestion/index.test.ts, test/gate-validation.test.ts
+```
+
+with:
+
+```
+**TEST**: src/model/spec-version.test.ts, src/registry/index.test.ts, src/ingestion/index.test.ts, test/gate-validation.test.ts, test/upstream-drift.test.ts
+```
+
+In the `R-039` block, replace the `**TEST**:` line:
+
+```
+**TEST**: src/registry/index.test.ts, test/gate-validation.test.ts
+```
+
+with:
+
+```
+**TEST**: src/registry/index.test.ts, test/gate-validation.test.ts, test/upstream-drift.test.ts
+```
+
+Leave both requirement **bodies** alone; Task 4 rewrites those.
+
+- [ ] **Step 5: Run the full gate set**
+
+```sh
+bun scripts/check-docs.ts && bun run lint && bun run typecheck && bun test
+```
+
+Expected: exit 0, `430 pass, 0 fail`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add test/upstream-drift.test.ts REQUIREMENTS.md
+git commit -m "test: gate offbook's hand-authored constants against @asyncapi/specs
+
+Three checks: the supported version set equals what @asyncapi/specs
+exposes, the mqtt operation-binding constants equal that schema's
+properties and patternProperties, and nothing under src/ imports
+@asyncapi/specs at any subpath.
+
+The first is what closes the gap the preflight leaves open. offbook
+refuses only versions it positively recognizes as untested, so a version
+the parser accepts and offbook does not would slip through; catching
+that at the dependency bump beats a runtime recheck, which would be a
+permanently uncovered throw while the two sets agree.
+
+The third is a source-text check rather than a lint rule because Biome's
+noRestrictedImports matches whole specifiers and cannot express a
+package at any subpath, which is the exact shape of the import it
+replaces."
+```
+
+---
+
+### Task 4: Requirements, decision, and doc updates
+
+**Files:**
+- Modify: `REQUIREMENTS.md` (R-037 body at line 298ff, R-039 body at line 314ff — their `TEST:` lines were done in Task 3)
+- Modify: `DECISIONS.md` (append after line 146)
+- Modify: `docs/specs/build-plan.md:21`
+
+`docs/specs/contracts.md` is deliberately **not** touched: the preflight's error text and the binding key set are `registry/` internals, and neither the `Diagnostic` shape nor the `spec-load` tag list moves, so the canonical contract is unaffected. `biome.json` is not touched either, per the Global Constraints.
+
+**Interfaces:**
+- Consumes: the behavior delivered by Tasks 1-3. Nothing consumes this task.
+
+- [ ] **Step 1: Update the R-037 body**
+
+Task 3 already added `test/upstream-drift.test.ts` to this requirement's `**TEST**:` line; leave that alone. In `REQUIREMENTS.md`, in the `R-037` block, replace its body paragraph:
+
+```
+`registry/` refuses any spec outside the tested support set (2.0.0-2.6.0, 3.0.0, 3.1.0) with a branded, actionable error naming the version, the range, and the convert remedy, checked parser-free before `parse()`; the declared version is recorded as `spec-version` in `specs.lock` and on `SpecInfo`.
+```
+
+with:
+
+```
+`registry/` refuses any spec whose declared version it can read and has not tested (the set is 2.0.0-2.6.0, 3.0.0, 3.1.0) with a branded, actionable error naming the version, every tested version, and the convert remedy, checked parser-free before `parse()`; an unreadable or absent `asyncapi` field defers to the parser's own diagnostics rather than being guessed at as a version problem (D-019), and a drift test keeps the tested set aligned with what `@asyncapi/specs` exposes; the declared version is recorded as `spec-version` in `specs.lock` and on `SpecInfo`.
+```
+
+- [ ] **Step 2: Update the R-039 body**
+
+Same here: the `**TEST**:` line is already done. In `REQUIREMENTS.md`, in the `R-039` block, replace its body paragraph:
+
+```
+`registry/` guards binding-supplied `qos`/`retain` values (falling through the §2 precedence chain on a bad value), reports unknown keys against the official mqtt operation-binding key set, reports an mqtt CHANNEL binding as ignored, and reports MQTT-5-only binding fields as unhonored under the MQTT 3.1.1-only constraint.
+```
+
+with:
+
+```
+`registry/` guards binding-supplied `qos`/`retain` values (falling through the §2 precedence chain on a bad value), reports unknown keys against a hand-authored mqtt operation-binding key set that honors the schema's `x-` vendor-extension pattern and is drift-tested against `@asyncapi/specs` (a devDependency, never imported from `src/`; D-019), reports an mqtt CHANNEL binding as ignored, and reports MQTT-5-only binding fields as unhonored under the MQTT 3.1.1-only constraint.
+```
+
+- [ ] **Step 3: Append D-019 to `DECISIONS.md`**
+
+Append after the current last line (line 146, D-018's `**Folds into**:` line), preserving the blank-line-then-heading rhythm of the file:
+
+```markdown
+
+### D-019: the version gate refuses only what it recognizes, and upstream constants are hand-authored behind a drift gate
+**Date**: 2026-08-01
+**What**: Amends D-018 on three mechanisms. (1) The R-037 preflight fires only on a version it positively read and positively recognizes as untested; an unreadable or absent `asyncapi` field falls through to `@asyncapi/parser`, and the refusal message names every tested version instead of a range. (2) The alignment between offbook's supported set and the parser's capability is enforced by an install-time drift test (`test/upstream-drift.test.ts`), not a runtime post-parse recheck. (3) `@asyncapi/specs` becomes a devDependency and the mqtt operation-binding key set becomes a hand-authored constant in `registry/`, transcribed including the `x-` vendor-extension pattern, with the same drift test pinning it and a source-text check keeping it out of `src/`.
+**Why**: Three defects found in PR #2 review. The preflight treated `readSpecVersion`'s `undefined` as "unsupported version", so malformed YAML, an empty file, and a fetched HTML error page all died advising `asyncapi convert`; spec-load failure aborts `up` in the foreground, so that was the whole error an adopter saw, and it fails the R-036 bar of naming what actually failed. The parser's own diagnostics already distinguish those cases precisely, so owning branded messages for them would duplicate correct text and put a second YAML reader in a position to disagree with the parser's. `@asyncapi/specs` was imported but undeclared, a transitive of `@asyncapi/parser` resolved only by flat hoisting, at an unversioned internal subpath the package's absent `exports` map does not guarantee. Deriving the binding key set at runtime also read only `properties`, dropping the schema's `patternProperties` allowance, so a spec-legal `x-vendor-thing` was reported as an unknown key.
+**Mitigations / notes**: A runtime `document.version()` recheck was considered for the gap the preflight leaves (a version the parser accepts and offbook does not) and rejected: it is structurally unreachable while the two sets agree, which they do, so it would ship as a permanently uncovered `throw` under the per-file coverage floor. The drift test catches the same divergence at the dependency bump instead. The re-import guard is a source-text check rather than a Biome `noRestrictedImports` rule because Biome 1.9 matches whole module specifiers: a bare `@asyncapi/specs` entry does not flag `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` (verified both ways), which is precisely the import shape being prevented. The drift test does not reopen what D-018 rejected: the constants stay hand-authored and separately tested against the real parser, and the test only makes upstream drift loud.
+**Discovered during implementation (2026-08-01)**: an unquoted `asyncapi: 2.6` (a YAML float, not a string) makes `@asyncapi/parser` 3.6.0 die inside `getSemver` with a raw `TypeError: undefined is not an object (evaluating 'patchWithRc.split')` stack dumped into a diagnostic. The preflight catches it first because `readSpecVersion` normalizes with `String()`, which retroactively justifies that normalization as load-bearing rather than defensive.
+**Obligations**: none deferred.
+**From**: code review of PR #2 (findings 1-3), then a design dialog on 2026-08-01; every behavioral claim verified empirically against the installed toolchain.
+**Folds into**: src/registry/index.ts, package.json, test/upstream-drift.test.ts, REQUIREMENTS.md (R-037, R-039), docs/specs/build-plan.md §1
+```
+
+- [ ] **Step 4: Note the dev-only dependency in `build-plan.md`**
+
+In `docs/specs/build-plan.md`, replace line 21:
+
+```
+| AsyncAPI | **`@asyncapi/parser`** (3.x) | parse + validate; dereferences `$ref` before validating (§5) |
+```
+
+with:
+
+```
+| AsyncAPI | **`@asyncapi/parser`** (`^3.6.0`) | parse + validate; dereferences `$ref` before validating (§5). Its `@asyncapi/specs` transitive is **also a devDependency**, used only by `test/upstream-drift.test.ts` to pin offbook's hand-authored version set and mqtt binding key set against the installed schemas; `src/` never imports it (D-019) |
+```
+
+- [ ] **Step 5: Run the doc-system gate**
+
+Run: `bun scripts/check-docs.ts`
+
+Expected: exit 0, reporting `39 requirements, 19 decisions, 0 intake file(s)`. The decision count rises from 18 because D-019 is new; the requirement count does not move, because this work amends R-037 and R-039 rather than adding a requirement.
+
+- [ ] **Step 6: Run the complete gate set**
+
+```sh
+bun scripts/check-docs.ts && bun run lint && bun run typecheck && bun run demo-app:build && bun test
+echo "gates exit=$?"
+```
+
+Expected: `gates exit=0`, with `bun test` reporting `430 pass, 0 fail`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add REQUIREMENTS.md DECISIONS.md docs/specs/build-plan.md
+git commit -m "docs: record D-019 and amend R-037/R-039
+
+R-037 said the preflight refuses any spec outside the tested set, which
+was too broad: it now refuses only a version it can read and has not
+tested, and defers the rest to the parser. R-039 said the key set comes
+from the official schema, which is now a hand-authored transcription
+behind a drift gate, honoring the vendor-extension pattern the derived
+set dropped.
+
+D-019 amends D-018 on the three mechanisms and records the unquoted
+\`asyncapi: 2.6\` parser TypeError found while designing."
+```
+
+---
+
+## Verification checklist
+
+Run from a clean tree after Task 4:
+
+```sh
+git status --porcelain          # expect: empty
+bun scripts/check-docs.ts       # expect: exit 0, 39 requirements, 19 decisions
+bun run lint                    # expect: exit 0
+bun run typecheck               # expect: exit 0
+bun run demo-app:build          # expect: exit 0
+bun test                        # expect: exit 0, 430 pass, 0 fail
+```
+
+Then confirm the adopter-visible behavior by hand:
+
+```sh
+# a YAML syntax error must NOT advise `asyncapi convert`
+bun -e 'import{buildRegistry}from"#src/registry/index.ts";import{DEFAULT_CONFIG}from"#src/model/index.ts";
+buildRegistry({specText:"asyncapi: 3.0.0\ninfo: {title: T\n  bad: ][",service:"a",config:DEFAULT_CONFIG})
+.catch(e=>console.log(e.message))'
+```
+
+Expected: a message starting `failed to parse spec:` that names the YAML problem and mentions neither `unsupported AsyncAPI version` nor `asyncapi convert`.
diff --git a/docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md b/docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
new file mode 100644
index 0000000..a4bbb24
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md
@@ -0,0 +1,135 @@
+# AsyncAPI 2.0.0 through 3.1.0 support: design
+
+**Date**: 2026-07-30
+**Status**: designed (not yet implemented)
+**Provenance**: brainstorm dialog 2026-07-30, following a deep-research pass the same day. Every behavioral claim in this document was verified empirically during the dialog by running the installed toolchain (`@asyncapi/parser` 3.6.0, `@asyncapi/specs` 6.11.1, `ajv` 8.20.0), plus isolated installs of parser 3.4.0 and 3.5.0. Primary-source citations were confirmed against the AsyncAPI spec text, `parser-js`, `converter-js`, and the `bindings` repo. See **Verification** for the raw results.
+
+## Problem
+
+Offbook ingests adopter-authored AsyncAPI specs and derives a normalized channel catalog used for mocking and bidirectional validation. The declared support surface is vague: `REQUIREMENTS.md` R-004 says direction resolves for "v2 + v3", no adopter-facing doc states a version range at all, and nothing preflights the version a spec declares.
+
+Behind that vagueness sit three defects in the shared ingestion path, all found by research rather than by any failing test:
+
+1. **A valid AsyncAPI 3.x document can silently disable validation entirely.** The spec permits the explicit multi-format payload form, `payload: {schemaFormat, schema}`. Because `registry/index.ts` spreads `msg.payload().json()`, that form yields a channel schema whose top-level keys are `$schema, schemaFormat, schema`, carrying no validation keywords. Such a channel accepts everything: wrong types, unrelated objects, a bare string, `null`. No error, no diagnostic, green forever. This is the false-negative class that R-028 exists to prevent, and no fixture uses that payload form.
+2. **A legal tuple payload schema crashes registry construction.** `{type: array, items: [...]}` is valid in both majors and parses fine, then `ajv.compile()` throws `schema is invalid: data/items must be object,boolean` because Offbook stamps 2020-12 over a schema the parser emitted as draft-07. Nothing catches the throw, so it surfaces as a raw Ajv error out of `bootProject` with no channel named.
+3. **AsyncAPI 2.x MQTT bindings are not schema-validated.** 2.x's meta-schema maps `mqtt` to an empty schema, so `{qos: 9, retian: true}` parses with zero errors and `qos: 9` flows into a `Channel` typed `qos: 0 | 1 | 2`. The identical binding fails loudly on 3.x.
+
+Defect 1 is an API-shape mistake: `BaseModel.json()` returns the raw node, and the code assumes it is always a bare schema. Defect 2 shares its root cause with the existing D-005 limitation: Offbook validates under a dialect the parser never produced.
+
+## Scope
+
+One hardening project covering both the declared version range and the correctness defects in the path that serves it, because a "we support 2.0.0 through 3.1.0" claim layered over a validator that can silently accept everything would be a false claim.
+
+In scope: the supported-version contract and its preflight, the payload schema boundary in `registry/`, MQTT binding integrity, fixtures and gates for the untested corners, and the doc/provenance updates. Out of scope items are listed at the end.
+
+## Decisions (from the design dialog)
+
+- **Scope is combined**, version breadth plus the three defects, for the reason above.
+- **Approach: harden the existing dual path**, not convert-on-ingest. `@asyncapi/converter` would deliver 2.x binding validation for free and collapse the direction logic to one path, but the org's specs are mostly 3.x, so the 2.x path is a shrinking minority not worth a new dependency plus a translation layer. Decisive factor: Offbook's value is telling a developer exactly which channel and payload broke, which argues for diagnostics anchored to the file they edit rather than to a machine-rewritten copy. Narrowing to 3.x-only was also rejected, as it abandons the stated goal.
+- **Offbook enforces its own supported-version gate** rather than relying on the parser's rejection, so 1.x users get an actionable message and an opaque ruleset failure cannot pass through unexplained.
+- **Payload validation moves to JSON Schema draft-07**, the dialect both spec majors declare and the one the parser actually emits. This is the root-cause fix for defect 2 and for the D-005 `$ref`-sibling limitation, and it requires no schema rewriting, so the no-hand-rolled-schema-interpretation constraint (R1) stays intact. Because draft-07 silently ignores 2020-12-only keywords, it is paired with a dialect-mismatch diagnostic.
+- **Binding policing is a value guard plus a key-set check sourced from the official binding schema**, not full Ajv validation against the bundled spec schema. Offbook consumes exactly two binding fields; reading the legal key list from `@asyncapi/specs` avoids hardcoding spec knowledge without loading a bundle or compiling schemas Offbook never uses.
+- **D-005's deferred obligation is closed as superseded**, with its tripwire retained and reworded. Under draft-07 the dropped `$ref` sibling is dialect-correct behavior, not a limitation awaiting a 2020-12 schema-parser spike.
+
+## 1. The support contract
+
+**Supported matrix**: 3.1.0 (recommended authoring target), 3.0.0, and 2.6.0 down through 2.0.0. Refused: all 1.x, the `2.0.0-rc1` and `2.0.0-rc2` release candidates (present on disk in `@asyncapi/specs` but excluded from its export map, so the parser never accepts them), and any document with a missing or unreadable `asyncapi` field.
+
+The supported set is an **explicit constant that a test cross-checks**, not `Object.keys(specs.schemas)`. Deriving it would reproduce exactly the trap that fooled parser 3.4.0: the schema file is present, the version gate passes, and the ruleset then fails. Offbook's supported set is a promise it tests, so it is written down.
+
+**Parser floor moves from `^3.4.0` to `^3.6.0`.** AsyncAPI 3.1.0 support landed in that release ("Release AsyncAPI 3.1 support that adds ROS 2 binding"). The floor is load-bearing rather than cosmetic: parser 3.4.0 and 3.5.0 both resolve `@asyncapi/specs` 6.11.1, which contains the 3.1.0 schema, pass their own dynamic version gate, and then die inside the Spectral ruleset with `AggregateError: Error running Nimma`. A caret range cannot protect against that.
+
+**Preflight gate.** A pure, parser-free helper (`src/model/spec-version.ts`, tier 0, using the `yaml` dependency already present) reads the `asyncapi` field from raw spec text. `registry/buildRegistry` calls it before `parser.parse()` and, on an unsupported or absent version, throws an Offbook-branded error naming the version found, the supported range, and the remedy (`asyncapi convert`). Placing the helper in `model/` keeps `registry/` and `ingestion/` as tier peers without a cross-import.
+
+**Version provenance becomes visible.** `ingestion/` already does a parser-free shallow `info.version` read (G12); it reads `asyncapi` in the same pass and records it as `spec-version` in `specs.lock` beside `declared-version`. The value joins `SpecInfo`, so `GET /v1/specs` and `offbook doctor` report which major each service is on. For a mostly-3.x fleet this turns "which teams are still on 2.x" into a question the tool answers.
+
+## 2. The payload schema boundary
+
+All of this lives in `registry/index.ts`, which is where the parser output becomes a `Channel`.
+
+**Unwrap the multi-format payload.** A helper extracts the schema, returning `payloadJson.schema` when the payload JSON is an object carrying an object-valued `schema` key alongside `schemaFormat`, and the payload JSON itself otherwise. This is the same discriminator the parser's own `Schema` model uses internally (`_schemaObject = _json.schema`); `BaseModel.json()` returns the raw node verbatim, which is why the wrapper leaks. The helper **must not** branch on the `schemaFormat` string value: the implementation emits `application/vnd.aai.asyncapi;version=X` while the spec text mandates a `+json` suffix, so literal comparison is a trap.
+
+**Validate under draft-07.** Replace the `Ajv2020` instance with Ajv's default draft-07 build, keep `ajv-formats`, and stamp `$schema: http://json-schema.org/draft-07/schema#` explicitly rather than 2020-12. The explicit stamp is verified equivalent to no stamp and makes `channel.schema` self-describing for consumers of `GET /topics`. Consequences, all verified: tuple `items` validates correctly, `additionalItems` is honored instead of silently ignored, and the `external-ref` correctness bar plus the D-005 tripwire behave identically.
+
+**Diagnose dialect mismatch.** Because draft-07 ignores unknown keywords, a payload authored with 2020-12 constructs would silently under-validate, which is the worst failure mode for this tool. A recursive scan flags `prefixItems`, `unevaluatedProperties`, `unevaluatedItems`, `dependentRequired`, `dependentSchemas`, `minContains`, `maxContains`, `$dynamicRef`, `$dynamicAnchor`, `$recursiveRef`, and `$recursiveAnchor`, surfacing a diagnostic naming service, topic, and keyword. `$defs` and `definitions` are **not** flagged: both resolve correctly under draft-07, and `fixtures/asyncapi/shared/common.yaml` legitimately uses `$defs`.
+
+**Contain compile failures.** The `ajv.compile()` call is wrapped. On failure the channel still enters the catalog, because discovery is a v1 floor that must survive weak specs, but its `validate` becomes a closure returning a single `SchemaError` describing the compile failure, so every payload on that channel yields an explicit violation instead of validating green. The failure also surfaces in `GET /v1/diagnostics` naming service, topic, and the Ajv message. No new field on `Channel` is required.
+
+**Handle multi-message operations.** When an operation declares more than one message, the channel schema becomes `anyOf` over each message's extracted payload schema; a single message keeps its schema directly. This preserves the single-schema `Channel` shape, so the faker and `/topics` are unaffected, and it fixes both v2 `message.oneOf` unions and v3 multi-message operations, where today only `messages()[0]` is read and variant-two payloads are wrongly reported as violations. `composition.yaml` already exercises `anyOf` through json-schema-faker with zero recheck failures (R-027/F8), so the faker path is known good.
+
+## 3. MQTT binding integrity
+
+**Value guard.** The `qos` read from a spec binding must be an integer in `{0, 1, 2}` and `retain` must be a boolean. On violation, Offbook surfaces a diagnostic naming service, topic, and the offending value, then **falls through to the next tier of the existing precedence chain** (`topicOverrides`, then per-service default, then global) rather than clamping the value or propagating it. This protects the `Channel` type invariant regardless of which spec version supplied the binding.
+
+**Key-set check.** The legal key list is read from `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json`'s `properties` (verified importable as JSON: `qos`, `retain`, `messageExpiryInterval`, `bindingVersion`). Any other key on an `mqtt` operation binding produces a diagnostic, which catches the misspelling class such as `retian` that 2.x accepts silently. Only the key list is read; the schema is deliberately not compiled, because it carries an unresolvable external `$ref` to `http://asyncapi.com/definitions/3.0.0/schema.json` and compiling it would require registering the whole bundled spec schema. Validating against 0.2.0 is the permissive-correct choice, since 0.2.0's property set is a superset of 0.1.0's.
+
+**Channel-binding diagnostic.** The MQTT Channel Binding Object "MUST NOT contain any properties. Its name is reserved for future use." at every binding version, so `qos`/`retain` are legal only at operation level. A 3.x document carrying `mqtt: {qos: 2}` on the channel nonetheless parses clean and Offbook silently uses the default. That becomes a diagnostic telling the author to move it to the operation.
+
+**MQTT 5 fields reported as unhonored.** Offbook is MQTT 3.1.1 only, so `messageExpiryInterval`, `payloadFormatIndicator`, `correlationData`, `contentType`, `responseTopic`, `sessionExpiryInterval`, and `maximumPacketSize` cannot be honored. Their presence produces a one-line notice rather than silence, consistent with the standing principle that the tool never lies about its own fidelity.
+
+## 4. Fixtures and tests
+
+**New fixtures**, both earning their place against the fixture quality bar rather than being version copies:
+
+| File | AsyncAPI | Exercises |
+|---|---|---|
+| `multi-format.yaml` | 3.1.0 | The explicit `{schemaFormat, schema}` payload form with a strict schema (`required` plus `additionalProperties: false`), on **both** a `send` and a `receive` operation so the hard case sits on every path that processes it. Doubles as the newest-supported-major acceptance fixture and the regression pin for the vacuous-validator defect. |
+| `v2-oldest.yaml` | 2.0.0 | The floor of the supported range: `subscribe` plus `publish` direction inversion, and an MQTT operation binding at `qos: 2`, which differs from both the global default (1) and any per-service default, so the binding assertion is not vacuous. |
+
+`composition.yaml` gains a tuple-form array payload, which validates correctly under the new dialect and would have crashed the registry before. Genuinely malformed cases stay out of `fixtures/`, matching the existing convention that fixtures are representative *valid* specs while negative cases are known-bad payloads; they live as inline test specs: the illegal 2.x binding, the channel-level binding, a `prefixItems` dialect mismatch, an uncompilable schema, and a multi-message operation.
+
+`fixtures/asyncapi/README.md` gains both rows, and its direction-mapping note gains the supported-version statement.
+
+**Tests and gates**:
+
+- A **version-matrix test** asserting every version in the supported constant parses, and that `1.2.0` and `2.0.0-rc1` fail with the branded error. This is also what keeps the constant honest.
+- A **vacuous-validator regression test** asserting the `multi-format.yaml` channel *rejects* a known-bad payload. This is the tripwire for the defect; if the unwrap regresses, it flips red rather than going quiet.
+- Registry unit tests per behavior: unwrap, dialect (tuple accepted, `additionalItems` honored), dialect-mismatch diagnostic, compile-failure containment, `anyOf` over multi-message operations, value guard fall-through, key-set diagnostic, channel-binding diagnostic, MQTT 5 notice.
+- **R-028**, the cross-cutting validation-correctness gate, extends to drive the new fixtures, so the false-negative class is covered by a v1 gate and not only by unit tests.
+- Arrow-tag comments (`// [utest->R-###]` and friends) on every new test, as the doc-system gate verifies tags in both directions.
+
+## 5. Doc and provenance changes
+
+- **`D-018`** records the version contract, the draft-07 dialect decision, and the binding policy, with a supersedes note pointing at D-005.
+- **`D-005`** gains a superseded-by note. Its deferred obligation (register a 2020-12 schema parser so `$ref` siblings survive) closes: under draft-07 the sibling is correctly ignored per the dialect both majors declare. The tripwire in `external-ref.yaml` and `registry/index.test.ts` is retained and reworded from "known limitation" to "dialect-correct behavior, pinned so a future dialect change is loud".
+- **`R-037`** supported-version contract, preflight gate, and `spec-version` provenance. **`R-038`** the payload schema boundary. **`R-039`** MQTT binding integrity. New ids rather than extending `R-004`, which is already `tested` and whose lifecycle the doc gate enforces.
+- **`docs/specs/contracts.md`** is canonical for types and endpoints, so it changes for: `spec-version` on `LockEntry` and `SpecInfo`; the dialect statement in §5 (currently "we only stamp `$schema: 2020-12`", which the dialect decision reverses); and the new `/v1/diagnostics` entries (`schema-compile-failed`, `binding-invalid-value`, `binding-unknown-key`, `binding-on-channel`, `mqtt5-field-ignored`, `dialect-mismatch`).
+- **`README.md`** and **`docs/guides/wiring-your-service.md`** state the supported range, recommend 3.1.0, and carry the v2 perspective caveat.
+- **`package.json`** parser floor to `^3.6.0`.
+
+## Known limitations
+
+- **A 2.x spec authored from the client's perspective loads with every direction inverted, and no tool can detect it.** The spec text is unambiguous (`subscribe` defines messages "produced by the application", `publish` defines messages "consumed by the application"), and Offbook's mapping matches it, as does `converter-js` under its default `pointOfView: 'application'`. But the convention is famously misread: `converter-js` ships a `pointOfView: 'client'` escape hatch and generator templates carry `view=provider` and `inverseOperations=true` flags for documents written the other way. This is documented for adopters, not solved.
+- **2020-12 keyword semantics are diagnosed, not honored.** An adopter writing `prefixItems` gets a diagnostic, not validation.
+- **Non-JSON-Schema payloads still fail the whole parse.** Avro, Protobuf, OpenAPI, and RAML payloads produce `Unknown schema format` and `document = null`. The multi-format unwrap in this design is a prerequisite for ever supporting them, since a registered schema parser returns its converted schema inside the same wrapper, but registering one is out of scope.
+- **A future parser bump changes the unknown-format behavior.** Parser `master` has softened `parseSchema()` to return `input.data` instead of throwing, so the hard failure is specific to 3.6.0 and should be re-verified on upgrade.
+- **`retain` applies to Publish only in binding 0.2.0**, narrowed from 0.1.0's "Publish, Subscribe". That narrowing is prose in the binding spec, not schema-enforced, so Offbook does not police it.
+
+## Out of scope
+
+- AsyncAPI 1.x support (reachable via `@asyncapi/converter`, which chains 1.0.0 through 3.1.0, but not pursued).
+- Convert-on-ingest as an architecture, and any bundled `offbook specs convert` verb.
+- Registering Avro, Protobuf, OpenAPI, or RAML schema parsers.
+- Honoring 2020-12 semantics natively (the custom schema-parser spike D-005 previously deferred).
+- MQTT 5, per the standing MQTT 3.1.1-only constraint.
+
+## Verification
+
+Run during the dialog against the installed toolchain unless noted.
+
+| Claim | Result |
+|---|---|
+| 1.x rejected | 1.2.0 gives `document = null`, `Version "1.2.0" is not supported. Please use "3.1.0" (latest) version of the specification.` |
+| 2.x parses, action not normalized | 2.0.0 and 2.6.0 parse; `op.action()` returns literal `publish`/`subscribe`, so both branches of `directionOf` are live |
+| 3.1.0 needs parser 3.6.0 | Isolated installs of 3.4.0 and 3.5.0 both resolve `@asyncapi/specs` 6.11.1, parse 3.0.0 fine, and fail 3.1.0 with `AggregateError: Error running Nimma` |
+| 3.1.0 is catalog-identical to 3.0.0 | All five 3.0.0 fixtures re-declared as 3.1.0 produce byte-identical catalogs (topic, direction, qos, retain, schema hash) through the real `buildRegistry` |
+| Multi-format payload is vacuous today | Through the real `buildRegistry`, a valid 3.0.0 multi-format channel accepts `{id: 42}`, `{unrelated: 1}`, `"nope"`, and `null`; top-level schema keys are `$schema, schemaFormat, schema` |
+| Tuple crash | `items: [...]` parses in 2.6.0 and 3.0.0, then `ajv.compile()` throws `schema is invalid: data/items must be object,boolean`; `prefixItems` compiles |
+| Draft-07 fixes it without regression | Under Ajv draft-07: tuple validates correctly (`[1,'a']` rejected), `additionalItems` honored, and the `external-ref` bar plus D-005 tripwire behave identically to 2020-12 |
+| Draft-07's cost | `prefixItems` is silently ignored under draft-07, hence the dialect-mismatch diagnostic |
+| 2.x bindings unvalidated | 2.6.0 with `{qos: 9, retian: true}` parses with zero errors and returns the value verbatim; identical binding on 3.0.0 fails parse (`Property "retian" is not expected to be here`) |
+| Binding key list is importable | `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` imports as JSON with `additionalProperties: false` and `qos` enum `[0,1,2]`; compiling it fails on an unresolvable external `$ref`, which is why only `properties` keys are read |
+| Channel-level binding is silently ignored | 3.0.0 with `mqtt: {qos: 2, retain: true}` on the channel parses clean; `op.bindings().get("mqtt")` is null and Offbook defaults to qos 1 |
+| Faker is dialect-safe | json-schema-faker 0.6.2 draws valid data for `prefixItems`, `dependentRequired`, `unevaluatedProperties`, `$defs` and `definitions` refs: 0 recheck failures across 12 seeds each |
+| `dependencies` is not a hazard | Draft-07 `dependencies` validates correctly under Ajv2020, so no migration concern either way |
+| Avro is rescuable but wrapper-bound | Registering `@asyncapi/avro-schema-parser` turns the parse failure into a converted JSON Schema, delivered inside the same `{schemaFormat, schema}` wrapper, which the current code would render vacuous |
diff --git a/docs/superpowers/specs/2026-08-01-asyncapi-version-gate-hardening-design.md b/docs/superpowers/specs/2026-08-01-asyncapi-version-gate-hardening-design.md
new file mode 100644
index 0000000..f7ffb04
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-01-asyncapi-version-gate-hardening-design.md
@@ -0,0 +1,212 @@
+# AsyncAPI version gate hardening: design
+
+**Date**: 2026-08-01
+**Status**: designed (not yet implemented)
+**Amends**: `docs/superpowers/specs/2026-07-30-asyncapi-version-support-design.md` (D-018, R-037, R-039). The substance of that design stands; three of its mechanisms change.
+**Provenance**: code review of PR #2 (findings 1, 2, and 3), then a design dialog on 2026-08-01. Every behavioral claim below was verified empirically against the installed toolchain (`@asyncapi/parser` 3.6.0, `@asyncapi/specs` 6.11.1) during the dialog. See **Verification** for the raw results.
+
+## Problem
+
+Three defects in the shipped R-037/R-039 implementation.
+
+1. **The version preflight swallows every parse failure and gives actively wrong advice.** `readSpecVersion` returns `undefined` both for "parsed fine, no `asyncapi` field" and for "did not parse at all", and the preflight runs before `parser.parse()`. So a malformed spec, an empty file, or a fetched HTML error page all die with:
+
+   ```
+   unsupported AsyncAPI version (no `asyncapi` field found) in service 'svc-a':
+   offbook supports 2.0.0 through 3.1.0. Convert the spec first:
+     `asyncapi convert <file> --target-version 3.1.0`
+   ```
+
+   All three are plausible first-run failures (a wrong `spec-path`, a wrong repo, an auth redirect returning HTML), all three previously reached the parser and surfaced its diagnostics through `failed to parse spec: …`, and `asyncapi convert` is the wrong remedy for every one of them. Spec-load failure is fatal and aborts `up` (design §7 Mode 1), so this message is the entire error the adopter sees. R-036 audited exactly this path and set the bar that every first-run error names what failed plus one concrete next step; this message fails that bar by naming the wrong failure.
+
+2. **`@asyncapi/specs` is imported but not declared.** `src/registry/index.ts` imports `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` to derive the legal mqtt operation-binding key set. That package is a transitive dependency of `@asyncapi/parser` (`^6.11.1`), not a declared one, so the import resolves only through flat hoisting. A parser upgrade that bumps or drops the dep, or an install under a non-hoisting layout, breaks the build. The path is also an unversioned internal file: the package publishes no `exports` map, so nothing guarantees the subpath is stable.
+
+3. **Legal vendor extensions are reported as unknown binding keys.** The derived key set reads only the schema's `properties`, ignoring its `patternProperties: ^x-[\w\d\.\x2d_]+$`, so a spec-legal `x-vendor-thing` on an mqtt operation binding raises a `binding-unknown-key` warning. Defect 3 is included because it lives in the exact lines defect 2 rewrites: hand-authoring a "legal key set" that is known not to be the legal key set would bake a false positive into a constant, where it is harder to notice than in derived code.
+
+Design work on defect 1 turned up a fourth, pre-existing, defect, recorded here and fixed as a side effect: an unquoted `asyncapi: 2.6` (a YAML float, not a string) makes the parser die with a raw stack trace inside a diagnostic, `TypeError: undefined is not an object (evaluating 'patchWithRc.split')`. That is the same opaque-parser-death class D-018 built the preflight for.
+
+## Scope
+
+In scope: the preflight's firing rule and message, the mechanism that keeps offbook's supported set aligned with the parser's, the `@asyncapi/specs` dependency boundary, and the vendor-extension allowance, plus the requirement, decision, and doc updates that follow.
+
+Out of scope: review findings 4 through 13 (the untested compose wiring, the mis-attributed `$ref`-sibling tripwire, the duplicated channel-binding diagnostic, the `dialect-mismatch` property-name false positive, the `schema: false` wrapper hole, and the nits). Each is independent of this change.
+
+## Decisions (from the design dialog)
+
+- **The gate refuses only what it positively recognizes as untested.** An unreadable or absent `asyncapi` field is not offbook's call to make. The alternative, owning a branded message for each of the three failure classes, duplicates two messages the parser already gets right and puts a second YAML reader in a position to disagree with the parser's about what "not YAML" means.
+- **Divergence between offbook's promise and the parser's capability is caught by an install-time drift test, not a runtime recheck.** A post-parse `document.version()` recheck is structurally unreachable while the two sets agree, which they do today, so it would ship as a permanently uncovered `throw` under a per-file coverage floor. The drift test catches the divergence at the dependency bump, which is the moment someone can act on it.
+- **`@asyncapi/specs` becomes a devDependency and the binding key set becomes a hand-authored constant**, extending to bindings the reasoning D-018 already applied to `SUPPORTED_SPEC_VERSIONS`: a value being present upstream is not the same as offbook having tested it. Declaring it as a runtime dependency instead would be a smaller diff but would leave production code deriving behavior from a package whose contents can change under a caret range.
+- **The refusal message names the tested set rather than a range.** After the firing-rule change the message appears only when a version was read and rejected, which is precisely the in-"range"-but-unsupported case where "2.0.0 through 3.1.0" would tell the user they are supported while refusing them.
+
+## 1. The version gate
+
+**Rule:** `registry/` refuses only a version it positively read and positively recognizes as untested. Everything else is the parser's verdict.
+
+```ts
+// R-037 preflight: check the declared version BEFORE handing the document to the
+// parser, because the parser's gate is derived from @asyncapi/specs at install time
+// and an unsupported-but-present version can pass it and then die opaquely inside
+// Spectral (D-018). Fires ONLY on a version this read positively resolved: an
+// unreadable or absent `asyncapi` field is not offbook's call to make, and the
+// parser's own diagnostics for those cases are accurate and specific (D-019).
+const specVersion = readSpecVersion(opts.specText);
+if (specVersion !== undefined && !isSupportedSpecVersion(specVersion)) {
+  throw new Error(
+    `unsupported AsyncAPI version "${specVersion}" in service '${opts.service}': ` +
+      `offbook supports ${SUPPORTED_SPEC_VERSIONS.join(", ")}. ` +
+      "Convert the spec first: `asyncapi convert <file> --target-version 3.1.0`",
+  );
+}
+```
+
+`readSpecVersion` keeps its `string | undefined` signature. `undefined` already means "I could not resolve a version", which is exactly the fall-through condition, so no discriminated result type is needed. `isSupportedSpecVersion` keeps its `undefined`-is-false semantics as a pure predicate; only the call site changes. The throw stays inline: option A leaves exactly one call site, so a message helper would be indirection for its own sake.
+
+The message becomes:
+
+```
+unsupported AsyncAPI version "2.7.0" in service 'svc-a': offbook supports 2.0.0,
+2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.6.0, 3.0.0, 3.1.0. Convert the spec first:
+  `asyncapi convert <file> --target-version 3.1.0`
+```
+
+A plain join of `SUPPORTED_SPEC_VERSIONS`, deliberately not collapsed to `2.0.0-2.6.0, 3.0.0, 3.1.0`. Collapsing reads better but needs a run-detection helper with its own edge cases (is `2.6.0` to `3.0.0` contiguous? is contiguity by minor or by patch?), which is cleverness inside a fatal error message. Nine names are noisier and cannot lie. The prose forms in `README.md` and the guides keep the collapsed rendering, where a human wrote and reviewed them.
+
+**What this changes for each input class:**
+
+| input | before | after |
+|---|---|---|
+| malformed YAML | version error, wrong remedy | the parser's syntax diagnostics via `failed to parse spec:` |
+| empty file, HTML error page, YAML with no `asyncapi` | version error, wrong remedy | `This is not an AsyncAPI document. The "asyncapi" field as string is missing.` |
+| `asyncapi: '1.2.0'` | branded refusal | branded refusal (unchanged behavior, new set rendering) |
+| unquoted `asyncapi: 2.6` | branded refusal | branded refusal, still ahead of the parser's `patchWithRc.split` TypeError |
+
+The fix strictly widens what the gate gets right: nothing that was correctly refused stops being refused.
+
+## 2. The `@asyncapi/specs` boundary
+
+`@asyncapi/specs` moves from undeclared-transitive to an explicit `devDependency` at `^6.11.1`. `src/registry/index.ts` drops its runtime import, so offbook's production dependency graph is unchanged from today's declared set.
+
+Both halves of the binding schema's key contract transcribe cleanly into `registry/`:
+
+```ts
+// The mqtt OPERATION binding's legal keys, transcribed from @asyncapi/specs'
+// bindings/mqtt/0.2.0/operation.json. Hand-authored and drift-tested rather than
+// derived at runtime, for the reason D-018 gave for SUPPORTED_SPEC_VERSIONS: a
+// value being present upstream is not the same as offbook having tested it.
+// Validating against 0.2.0 stays permissive-correct: its property set is a
+// superset of 0.1.0's.
+const MQTT_OPERATION_KEYS = new Set([
+  "bindingVersion", "messageExpiryInterval", "qos", "retain",
+]);
+
+// The same schema permits vendor extensions. Transcribed character-for-character
+// from its `patternProperties` key, so the drift test compares source strings
+// rather than approximating the intent.
+const MQTT_EXTENSION_KEY = /^x-[\w\d\.\x2d_]+$/;
+```
+
+The transcription round-trips exactly: `MQTT_EXTENSION_KEY.source === Object.keys(schema.patternProperties)[0]` is `true`. The unknown-key filter gains `&& !MQTT_EXTENSION_KEY.test(k)`, which is the whole of the defect-3 fix.
+
+**The re-import guard is a source-text check, not a lint rule.** Biome 1.9's `noRestrictedImports.paths` matches the exact module specifier string: a bare `@asyncapi/specs` entry does not flag `@asyncapi/specs/bindings/mqtt/0.2.0/operation.json` (verified both ways, see **Verification**). Since the realistic regression is a deep JSON path, a lint rule would be a no-op against the very import it is meant to prevent, and listing today's path would catch only today's path.
+
+The guard therefore follows the repo's established idiom for this constraint, the one `test/transport-isolation.test.ts` uses for the aedes family and `src/ingestion/index.test.ts` uses for G12: walk `src/**/*.ts` and regex the import edge. That catches every subpath, present and future. It lives as a third check in `test/upstream-drift.test.ts`, beside the two drift checks it belongs with.
+
+One consequence worth naming: the `binding-unknown-key` diagnostic's `detail` lists the legal keys, and it now lists them from the constant rather than from the derived set. The same four names today, and the drift test is what keeps that true.
+
+## 3. The upstream drift gate
+
+`test/upstream-drift.test.ts` (new) sits beside the existing structural gates `transport-isolation.test.ts` and `import-style.test.ts`, and carries `// [stest->R-037]` and `// [stest->R-039]`.
+
+1. **Version set.** `SUPPORTED_SPEC_VERSIONS` equals `Object.keys(specs.schemas)`. Exact equality, no filtering: the `2.0.0-rc1`/`2.0.0-rc2` schemas are present on disk but excluded from the export map, so the installed 6.11.1 exposes exactly the nine supported versions. The day a parser bump adds or removes one, offbook's promise and the parser's capability diverge and this goes red at the bump.
+
+   This does not reopen what D-018 rejected. D-018 refused to *derive* the constant, because a schema being present does not mean the ruleset handles it (parser 3.4.0 and 3.5.0 accepted 3.1.0 and then died in Nimma, which this test would not have caught, since 3.1.0 was present and listed). The constant stays hand-authored and separately tested against the real parser; this test only makes upstream drift loud so a human decides whether to test-and-add.
+
+2. **Binding key set.** `MQTT_OPERATION_KEYS` equals the schema's `properties` keys, and `MQTT_EXTENSION_KEY.source` equals its sole `patternProperties` key.
+
+3. **Re-import guard.** No file under `src/` imports `@asyncapi/specs` at any subpath, so the devDependency boundary holds.
+
+## 4. Tests
+
+`src/registry/index.test.ts` gains four cases and rewrites one:
+
+| case | asserts |
+|---|---|
+| rewrite: "refuses a spec with no asyncapi field" | the parser's `This is not an AsyncAPI document. The "asyncapi" field as string is missing.` reaches the caller through `failed to parse spec:`, not a version error |
+| new: malformed YAML | the parser's syntax diagnostics surface; the message does not mention `asyncapi convert` |
+| new: unquoted `asyncapi: 2.6` | the branded gate fires first, so the caller never sees the parser's `patchWithRc.split` TypeError |
+| new: `x-vendor-thing` on an mqtt operation binding | zero `binding-unknown-key` diagnostics |
+| update: the 1.x refusal | the message names every version in `SUPPORTED_SPEC_VERSIONS`, and the assertion is built from the constant so it cannot drift |
+
+`src/model/spec-version.test.ts` is unchanged. Its existing YAML-numeric case ("a YAML-numeric version is normalized to a string") reads as defensive trivia today; a comment now records that an unquoted `2.6` is what stands between an adopter and a raw parser stack trace.
+
+Three assertions are worth a mutation check before calling this done, because each can pass for the wrong reason:
+
+- reverting the `specVersion !== undefined` guard must turn the malformed-YAML case red;
+- dropping `MQTT_EXTENSION_KEY` from the unknown-key filter must turn the `x-` case red;
+- perturbing either constant must turn the drift gate red.
+
+## 5. Doc and provenance changes
+
+**`REQUIREMENTS.md`.** Both entries gain `test/upstream-drift.test.ts` in `TEST`; `IMPL` is unchanged for both.
+
+- **R-037** currently reads "refuses any spec outside the tested support set … checked parser-free before `parse()`", which is now too broad. It becomes: refuses any spec whose declared version it can read and has not tested, checked parser-free before `parse()`; an unreadable or absent `asyncapi` field defers to the parser's own diagnostics rather than guessing.
+- **R-039** currently reads "reports unknown keys against the official mqtt operation-binding key set". It becomes: against a hand-authored key set drift-tested against that schema, honoring the vendor-extension pattern.
+
+**`DECISIONS.md`.** One new entry, **D-019**, amending D-018 rather than superseding it, recording the four decisions above plus the two defects found while designing (the unquoted-`2.6` parser TypeError, and the derived key set rejecting legal `x-` extensions).
+
+**`docs/specs/build-plan.md`** §1 gets a note on the AsyncAPI row naming `@asyncapi/specs` as a dev-only drift-gate dependency. **`biome.json` is untouched**, per the source-text-guard decision in §2.
+
+**`docs/specs/contracts.md` needs no change.** The preflight's error text and the binding key set are `registry/` internals; neither the `Diagnostic` shape nor the `spec-load` tag list moves, so the canonical contract is untouched.
+
+## Out of scope
+
+Review findings 4 through 13, each independent of this change:
+
+- the compose wiring (`src/compose/index.ts:185`) and `mergeRegistries` diagnostics concatenation are untested end to end, so every registry diagnostic is unit-only;
+- the reworded `$ref`-sibling tripwire cannot detect a dialect change, because `@asyncapi/parser` erases the sibling during dereference before Ajv sees anything, so the causal chain asserted in five places is mis-attributed;
+- `binding-on-channel` fires once per operation rather than once per channel, duplicating on a channel with both a `send` and a `receive`;
+- `dialect-mismatch` walks property names and enum values, so a property literally named `prefixItems` is falsely flagged;
+- a `{schemaFormat, schema: false}` payload still accepts everything, since `extractPayloadSchema` requires `typeof schema === "object"`;
+- the remaining nits (triple YAML parse of spec text, the truncated `contracts.md` §1 sentence, the redundant spread in `mergeRegistries`, the MQTT5/unknown-key double report, and `shared/common.yaml` still declaring 2020-12).
+
+## Verification
+
+Run against the installed toolchain on 2026-08-01 (`@asyncapi/parser` 3.6.0, `@asyncapi/specs` 6.11.1, Bun 1.3.14).
+
+**Parser diagnostics for the inputs the preflight currently swallows:**
+
+| input | `parser.parse()` error |
+|---|---|
+| malformed YAML | `Invalid mixed usage of block and flow styles`, `Unexpected end of the stream within a flow collection` |
+| empty file | `This is not an AsyncAPI document. The "asyncapi" field as string is missing.` |
+| HTML 404 page | same as above |
+| valid YAML, no `asyncapi` field | same as above |
+| `asyncapi:` as a list | same as above, plus `"asyncapi" property type must be string` |
+| `asyncapi: '1.2.0'` | `Version "1.2.0" is not supported. Please use "3.1.0" (latest) version of the specification.` |
+| `asyncapi: '2.7.0'` | `Version "2.7.0" is not supported. …` |
+
+**`document.version()`** returns `"3.0.0"`, `"2.6.0"`, `"2.0.0"` for those documents, and `undefined` for an unquoted `asyncapi: 2.6`, which produces no document and this diagnostic:
+
+```
+Error thrown during AsyncAPI document validation. Name: TypeError, message: undefined
+is not an object (evaluating 'patchWithRc.split'), stack: TypeError: … at getSemver
+(node_modules/@asyncapi/parser/cjs/utils.js:17:25) at assertValidAsyncAPIVersion
+(node_modules/@asyncapi/parser/cjs/ruleset/formats.js:32:32) …
+```
+
+**`@asyncapi/specs` 6.11.1 surface:**
+
+- `Object.keys(specs.schemas)` is `["2.0.0","2.1.0","2.2.0","2.3.0","2.4.0","2.5.0","2.6.0","3.0.0","3.1.0"]`, exactly `SUPPORTED_SPEC_VERSIONS`, with no rc entries to filter.
+- `bindings/mqtt/0.2.0/operation.json` `properties` keys are `["bindingVersion","messageExpiryInterval","qos","retain"]`.
+- its sole `patternProperties` key is `"^x-[\\w\\d\\.\\x2d_]+$"`, and `/^x-[\w\d\.\x2d_]+$/.source` equals it.
+- that pattern accepts `x-vendor-thing` and `x-a.b`; it rejects `x-`, `x-foo!`, `qos`, and `xfoo`.
+
+**Current behavior confirmed defective:**
+
+- all three malformed inputs above produce the version error with the `asyncapi convert` remedy;
+- `x-vendor-thing` on an mqtt operation binding produces `binding-unknown-key: 't/ext' mqtt operation binding has unknown key(s) x-vendor-thing; the mqtt binding defines bindingVersion, messageExpiryInterval, qos, retain`;
+- `@asyncapi/specs` appears in `bun.lock` only as a dependency of `@asyncapi/parser`, and `package.json` declares neither a dependency nor a devDependency on it.
+
+**Biome `noRestrictedImports` specifier matching** (why the guard is a source-text check). With `"@asyncapi/specs"` added to `paths` for `src/**`, `bun run lint` does not flag `src/registry/index.ts:2`. With the exact string `"@asyncapi/specs/bindings/mqtt/0.2.0/operation.json"` instead, it flags that line immediately. The rule matches whole specifiers, not package prefixes, so it cannot express "this package at any subpath". `biome.json` was restored unmodified after the probe.
+
+**Baseline at `f6abb11`** (the state this design amends): `bun scripts/check-docs.ts`, `bun run lint`, `bun run typecheck`, and `bun test` (423 pass, 0 fail) each exit 0.
diff --git a/fixtures/asyncapi/README.md b/fixtures/asyncapi/README.md
index 715aeb8..64d9930 100644
--- a/fixtures/asyncapi/README.md
+++ b/fixtures/asyncapi/README.md
@@ -6,9 +6,11 @@ Representative specs for developing and testing `registry/`, `validation/`, and
 |---|---|---|
 | `thermostat.yaml` | 3.0.0 | Both directions (`fromClient` command + `toClient` state), topic params, enums — the running example |
 | `composition.yaml` | 3.0.0 | `allOf` / `oneOf` (const-discriminated) / `anyOf` — json-schema-faker weak spots; the Ajv recheck must catch non-conforming output (§4). The oneOf sits on **both** a `send` (toClient) and a `receive` (fromClient) operation, so the hard schema is validated on the client-publish path too |
-| `external-ref.yaml` + `shared/common.yaml` | 3.0.0 | External `$ref` across files + `$id` base URI — the parser bundling/dereference correctness bar (§5, §12.4). Also carries a `$ref` **sibling keyword** (`minLength`) that a 2020-12 dialect *should* honor but the draft-07 parser drops: a **known limitation (D-005)**, pinned by a tripwire test, deferred to a 2020-12 schema-parser spike |
+| `external-ref.yaml` + `shared/common.yaml` | 3.0.0 | External `$ref` across files + `$id` base URI — the parser bundling/dereference correctness bar (§5, §12.4). Also carries a `$ref` **sibling keyword** (`minLength`), which is **correctly not enforced**: draft-07 is the dialect both majors declare and the one offbook validates under, and draft-07 ignores keywords beside a `$ref`. Dialect-correct behavior rather than a limitation (D-018 supersedes D-005), pinned by a tripwire test so a future dialect change starts enforcing it loudly |
 | `v2-pubsub.yaml` | 2.6.0 | `publish`/`subscribe` — the perspective inversion on the **older** major |
 | `qos-retain.yaml` | 3.0.0 | MQTT operation bindings declaring qos/retain — the **binding** tier (tier 1) of the precedence chain (P1.D2) |
+| `multi-format.yaml` | 3.1.0 | The explicit Multi Format Schema Object payload (`{schemaFormat, schema}`) on **both** a `send` and a `receive` operation — the wrapper the parser returns verbatim, which made the validator accept everything (D-018). Also the newest-supported-major acceptance fixture |
+| `v2-oldest.yaml` | 2.0.0 | The **floor** of the supported range: `publish`/`subscribe` inversion plus a 2.x mqtt operation binding at `qos: 2` (2.x validates bindings not at all, so offbook checks them itself) |
 | `qos-overrides.yaml` | 3.0.0 | toClient channels with **no** binding — the **config** tiers: a `topicOverrides` per-topic override (tier 2, here `qos 0` — distinct from both global `qos 1` and the per-service default `qos 2`) beats a `qosDefault`/`retainDefault` per-service default (tier 3), via a paired `services.yaml` (`docs/specs/contracts.md` §2/§6, gap G13) |
 
 ## Direction mapping the registry must produce
@@ -19,6 +21,9 @@ Normalize once onto the `Channel` record (§5, `docs/specs/contracts.md` §1). N
 
 (In every fixture the *documented application is the SERVICE*; the browser application is the client/counterparty.)
 
+## Supported AsyncAPI versions
+offbook supports **2.0.0 through 2.6.0, 3.0.0, and 3.1.0** (D-018); 3.1.0 is the recommended authoring target. AsyncAPI 1.x is refused: convert it first. Fixtures should stay within this range, and the range itself is pinned by a test over `SUPPORTED_SPEC_VERSIONS`.
+
 ## Fixture quality bar (author + review checklist)
 
 A fixture's job is to *test something*, so it must clear these — the **"does this actually test what it claims?"** bar. Apply it both when adding a fixture and as a distinct review angle (the validity-only angle misses all of these):
@@ -26,7 +31,7 @@ A fixture's job is to *test something*, so it must clear these — the **"does t
 1. **No vacuous values.** Anything meant to exercise a behavior must **differ from the default/trivial outcome**, or a no-logic implementation passes anyway. *(Trap: a binding `qos: 1` when the global default is already `qos 1` — the precedence assertion proves nothing. Use a value that differs, e.g. `qos: 2`.)*
 2. **Claim ↔ content match.** Whatever the fixture's description says it exercises must be **structurally present**. *(Claim "`$ref` sibling keyword" → there must be a `$ref` with a sibling; claim "oneOf trap" → mutually-exclusive branches must actually exist.)*
 3. **Full-path coverage.** A hard case must sit on **every path that processes it**, or the gap is documented. *(A oneOf / external-`$ref` schema only on a `toClient` operation leaves client-publish (`fromClient`) validation of the hard case untested end-to-end.)*
-4. **Internal consistency.** `port` ↔ `protocol`, declared `schemaFormat`/dialect ↔ keywords used (`$defs`/`$id` need 2020-12), `asyncapi` version ↔ structure (v2 `publish`/`subscribe` vs v3 `operations`).
+4. **Internal consistency.** `port` ↔ `protocol`, declared `schemaFormat`/dialect ↔ keywords used (offbook validates payloads under **draft-07**, so a fixture leaning on a post-draft-07 keyword such as `prefixItems` is testing a diagnostic, not a validation), `asyncapi` version ↔ structure (v2 `publish`/`subscribe` vs v3 `operations`).
 5. **Negative cases exist.** Something must exercise the **rejection** path — a known-bad payload that *must* fail validation — not just happy-path validity.
 
 This bar generalizes to any test fixtures / golden files, not just AsyncAPI specs.
diff --git a/fixtures/asyncapi/external-ref.yaml b/fixtures/asyncapi/external-ref.yaml
index e89e0a2..3887037 100644
--- a/fixtures/asyncapi/external-ref.yaml
+++ b/fixtures/asyncapi/external-ref.yaml
@@ -6,11 +6,12 @@ info:
     Payloads reference an external file (shared/common.yaml) that carries its own
     $id base URI. Exercises the parser bundling/dereference + $id base-resolution
     correctness bar (§5, §12.4): the external Identifier's `pattern` must be inlined
-    and enforced under Ajv 2020 standalone, and a bad nodeId must be rejected.
-    KNOWN LIMITATION (DECISIONS.md D-005): a `$ref` SIBLING keyword (`minLength`,
-    below) is meant to apply under 2020-12 but is silently dropped by
-    @asyncapi/parser's draft-07 schema parser — the §12.4 silent-wrongness, deferred
-    to a dedicated 2020-12 schema-parser spike.
+    and enforced under Ajv standalone, and a bad nodeId must be rejected.
+    Also carries a `$ref` SIBLING keyword (`minLength`, below): a 2020-12 reader
+    would honor it, a draft-07 reader ignores it, and draft-07 is the dialect BOTH
+    spec majors declare and the parser emits, so offbook validating under it means
+    the sibling is correctly NOT enforced (D-018 supersedes D-005's deferred 2020-12
+    spike). A tripwire test pins this so a future dialect change is loud.
 servers:
   mosquitto:
     host: localhost:1883
@@ -43,10 +44,12 @@ components:
       additionalProperties: false
       properties:
         nodeId:
-          # $ref + SIBLING keyword. Under 2020-12 `minLength` would apply ALONGSIDE the ref's
-          # `pattern`; @asyncapi/parser normalizes to draft-07, which DROPS $ref siblings — so
-          # minLength is NOT enforced (KNOWN LIMITATION, D-005, §12.4). The external `pattern`
-          # IS inlined + enforced. See the tripwire in registry/index.test.ts.
+          # $ref + SIBLING keyword. A 2020-12 reader would apply `minLength` ALONGSIDE the ref's
+          # `pattern`; a draft-07 reader ignores $ref siblings, and draft-07 is the dialect BOTH
+          # spec majors declare and the parser emits, so offbook validating under it means
+          # minLength is correctly NOT enforced (D-018 supersedes D-005's deferred 2020-12 spike).
+          # The external `pattern` IS inlined + enforced. The tripwire in registry/index.test.ts
+          # pins this so a future dialect change is loud rather than silent.
           $ref: 'shared/common.yaml#/$defs/Identifier'
           minLength: 3
         recordedAt:
diff --git a/fixtures/asyncapi/multi-format.yaml b/fixtures/asyncapi/multi-format.yaml
new file mode 100644
index 0000000..ef7aad7
--- /dev/null
+++ b/fixtures/asyncapi/multi-format.yaml
@@ -0,0 +1,63 @@
+asyncapi: 3.1.0
+info:
+  title: Multi Format Payloads
+  version: 1.0.0
+  description: >-
+    Payloads authored as the explicit Multi Format Schema Object
+    (`{schemaFormat, schema}`), which AsyncAPI 3.x permits for the DEFAULT
+    JSON-Schema format, not just for Avro or Protobuf. The parser returns that
+    wrapper verbatim from `payload().json()`, so a consumer that spreads it gets
+    a schema with no validation keywords: a validator that accepts everything
+    (D-018). Both directions carry the form, so the client-publish path is
+    covered too. Also the newest-supported-major acceptance fixture.
+servers:
+  mosquitto:
+    host: localhost:1883
+    protocol: mqtt
+    protocolVersion: '3.1.1'
+channels:
+  reading:
+    address: reading/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Reading:
+        name: Reading
+        payload:
+          schemaFormat: 'application/vnd.aai.asyncapi;version=3.1.0'
+          schema:
+            type: object
+            required: [sensorId, celsius]
+            additionalProperties: false
+            properties:
+              sensorId:
+                type: string
+              celsius:
+                type: number
+  calibrate:
+    address: calibrate/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Calibrate:
+        name: Calibrate
+        payload:
+          schemaFormat: 'application/vnd.aai.asyncapi;version=3.1.0'
+          schema:
+            type: object
+            required: [offset]
+            additionalProperties: false
+            properties:
+              offset:
+                type: number
+operations:
+  sendReading:
+    action: send
+    channel:
+      $ref: '#/channels/reading'
+  receiveCalibrate:
+    action: receive
+    channel:
+      $ref: '#/channels/calibrate'
diff --git a/fixtures/asyncapi/v2-oldest.yaml b/fixtures/asyncapi/v2-oldest.yaml
new file mode 100644
index 0000000..1192e4b
--- /dev/null
+++ b/fixtures/asyncapi/v2-oldest.yaml
@@ -0,0 +1,62 @@
+asyncapi: '2.0.0'
+info:
+  title: Oldest Supported Major
+  version: 1.0.0
+  description: >-
+    AsyncAPI 2.0.0, the FLOOR of offbook's supported range (D-018). Pins that
+    the oldest major still parses, that `publish`/`subscribe` normalize to
+    fromClient/toClient, and that a 2.x mqtt OPERATION binding is read (2.x maps
+    `mqtt` to an empty schema in its own meta-schema, so nothing validates it
+    upstream: offbook checks the values and keys itself).
+servers:
+  mosquitto:
+    url: localhost:1883
+    protocol: mqtt
+    protocolVersion: '3.1.1'
+channels:
+  legacy/{deviceId}/telemetry:
+    parameters:
+      deviceId:
+        schema:
+          type: string
+    subscribe:                     # service publishes ⇒ client receives ⇒ toClient
+      operationId: sendTelemetry
+      bindings:
+        mqtt:
+          qos: 2                   # differs from the global default (1): a real assertion
+          retain: true
+          bindingVersion: '0.1.0'
+      message:
+        $ref: '#/components/messages/Telemetry'
+  legacy/{deviceId}/command:
+    parameters:
+      deviceId:
+        schema:
+          type: string
+    publish:                       # client publishes ⇒ service receives ⇒ fromClient
+      operationId: receiveCommand
+      message:
+        $ref: '#/components/messages/Command'
+components:
+  messages:
+    Telemetry:
+      name: Telemetry
+      payload:
+        type: object
+        required: [deviceId, celsius]
+        additionalProperties: false
+        properties:
+          deviceId:
+            type: string
+          celsius:
+            type: number
+    Command:
+      name: Command
+      payload:
+        type: object
+        required: [mode]
+        additionalProperties: false
+        properties:
+          mode:
+            type: string
+            enum: [heat, cool, off]
diff --git a/package.json b/package.json
index 4a981f7..e12c0cb 100644
--- a/package.json
+++ b/package.json
@@ -23,7 +23,7 @@
 		"demo-app": "bun demo-app/serve.ts"
 	},
 	"dependencies": {
-		"@asyncapi/parser": "^3.4.0",
+		"@asyncapi/parser": "^3.6.0",
 		"aedes": "^0.51.3",
 		"aedes-server-factory": "^0.2.1",
 		"ajv": "^8.17.1",
@@ -34,6 +34,7 @@
 		"yaml": "^2.5.0"
 	},
 	"devDependencies": {
+		"@asyncapi/specs": "^6.11.1",
 		"@biomejs/biome": "^1.9.0",
 		"@hughescr/stryker-bun-runner": "^1.3.8",
 		"@stryker-mutator/core": "^9.6.1",
diff --git a/scripts/spike-jsf-fidelity.ts b/scripts/spike-jsf-fidelity.ts
index c28e136..160176c 100644
--- a/scripts/spike-jsf-fidelity.ts
+++ b/scripts/spike-jsf-fidelity.ts
@@ -8,9 +8,11 @@ import { buildRegistry } from "#src/registry/index.ts";
 export const SPIKE_FIXTURES = [
 	"composition.yaml",
 	"external-ref.yaml",
+	"multi-format.yaml",
 	"qos-overrides.yaml",
 	"qos-retain.yaml",
 	"thermostat.yaml",
+	"v2-oldest.yaml",
 	"v2-pubsub.yaml",
 ];
 
diff --git a/src/cli/boot.ts b/src/cli/boot.ts
index 93bb1c9..9645bfe 100644
--- a/src/cli/boot.ts
+++ b/src/cli/boot.ts
@@ -73,6 +73,7 @@ export async function bootProject(opts: ProjectBootOptions): Promise<Composed> {
 			infos.push({
 				service: name,
 				declaredVersion: spec.declaredVersion,
+				specVersion: spec.specVersion,
 				source: spec.source,
 				contentHash: spec.contentHash,
 				channelCount: registry.channels().length,
diff --git a/src/compose/index.ts b/src/compose/index.ts
index 2a7973d..1b60aa9 100644
--- a/src/compose/index.ts
+++ b/src/compose/index.ts
@@ -182,6 +182,7 @@ export async function compose(parts: ComposeParts) {
 
 		diagnostics: () => [
 			...(runtime?.diagnostics() ?? []),
+			...registry.diagnostics(),
 			...specQualityDiagnostics(registry.channels()),
 			...uninstantiatedDiagnostics(
 				registry.channels(),
diff --git a/src/control-plane/index.test.ts b/src/control-plane/index.test.ts
index d95a7d7..6ed769e 100644
--- a/src/control-plane/index.test.ts
+++ b/src/control-plane/index.test.ts
@@ -113,6 +113,7 @@ function makeChannel(
 
 function fakeRegistry(channels: Channel[]): SpecRegistry {
 	return {
+		diagnostics: () => [],
 		channels: () => channels,
 		match: (topic) => {
 			const c = channels.find((ch) => ch.topic === topic);
diff --git a/src/engine/dispatch.test.ts b/src/engine/dispatch.test.ts
index 59e2f75..a80e056 100644
--- a/src/engine/dispatch.test.ts
+++ b/src/engine/dispatch.test.ts
@@ -17,6 +17,7 @@ import {
 // (the real matcher behavior is R-004-tested in registry/; dispatch only
 // delegates to it, so a stub keeps this test transport- and parser-free).
 const stubRegistry: SpecRegistry = {
+	diagnostics: () => [],
 	match(topic: string) {
 		const mk = (address: string, params: Record<string, string>) => ({
 			channel: {
diff --git a/src/engine/index.test.ts b/src/engine/index.test.ts
index b031b05..baba7cd 100644
--- a/src/engine/index.test.ts
+++ b/src/engine/index.test.ts
@@ -41,6 +41,7 @@ function makeChannel(
 function makeRegistry(): SpecRegistry {
 	const state = makeChannel("state/{deviceId}", stateSchema, 2, true);
 	return {
+		diagnostics: () => [],
 		match(topic: string) {
 			const m = topic.match(/^state\/([^/]+)$/);
 			if (m?.[1]) return { channel: state, params: { deviceId: m[1] } };
@@ -399,6 +400,7 @@ test("tick() dispatches every handler in precedence order; the tick index advanc
 function permissiveRegistry(): SpecRegistry {
 	const ch = makeChannel("thing/{id}", { type: "object" }, 1, false);
 	return {
+		diagnostics: () => [],
 		match(topic: string) {
 			const m = topic.match(/^thing\/([^/]+)$/);
 			if (m?.[1]) return { channel: ch, params: { id: m[1] } };
@@ -412,6 +414,7 @@ function permissiveRegistry(): SpecRegistry {
 function brokenRegistry(): SpecRegistry {
 	const ch = makeChannel("broken/{id}", { not: {} }, 1, true);
 	return {
+		diagnostics: () => [],
 		match(topic: string) {
 			const m = topic.match(/^broken\/([^/]+)$/);
 			if (m?.[1]) return { channel: ch, params: { id: m[1] } };
@@ -568,6 +571,7 @@ test("a '+' inside a topic level is not a wildcard: the subscribe materializes (
 function literalRegistry(): SpecRegistry {
 	const ch = makeChannel("plain/topic", { type: "object" }, 1, false);
 	return {
+		diagnostics: () => [],
 		match: (topic: string) =>
 			topic === "plain/topic" ? { channel: ch, params: {} } : undefined,
 		matchesFilter: () => false,
@@ -735,6 +739,7 @@ function fromClientRegistry(): SpecRegistry {
 		retain: false,
 	};
 	return {
+		diagnostics: () => [],
 		match(topic: string) {
 			const m = topic.match(/^cmd\/([^/]+)$/);
 			if (m?.[1]) return { channel: ch, params: { id: m[1] } };
diff --git a/src/engine/instances.test.ts b/src/engine/instances.test.ts
index 99c1914..c9b7b41 100644
--- a/src/engine/instances.test.ts
+++ b/src/engine/instances.test.ts
@@ -100,6 +100,7 @@ function makeWiringRegistry(): SpecRegistry {
 	const command = makeChannel("command/{deviceId}/set", "fromClient", false);
 	const all = [status, state, command];
 	return {
+		diagnostics: () => [],
 		match(topic: string) {
 			if (topic === "status/all")
 				return { channel: status, params: {} as Record<string, string> };
diff --git a/src/engine/reset.test.ts b/src/engine/reset.test.ts
index bf6a333..d1d61ae 100644
--- a/src/engine/reset.test.ts
+++ b/src/engine/reset.test.ts
@@ -28,6 +28,7 @@ function makeRegistry(): SpecRegistry {
 		retain: true,
 	};
 	return {
+		diagnostics: () => [],
 		match: (topic: string) => {
 			const m = topic.match(/^state\/([^/]+)$/);
 			return m?.[1] ? { channel: ch, params: { id: m[1] } } : undefined;
diff --git a/src/ingestion/index.test.ts b/src/ingestion/index.test.ts
index 9d21833..2eef8c3 100644
--- a/src/ingestion/index.test.ts
+++ b/src/ingestion/index.test.ts
@@ -151,6 +151,8 @@ test("resolveServices resolves all services (bounded), warns per branch, builds
 	expect(lockfile.resolutionMode).toBe("branch");
 	expect(lockfile.services.svc.requestedVersion).toBe("9.9.9"); // recorded, unhonored (v1)
 	expect(lockfile.services.svc.declaredVersion).toBe("4.2.0");
+	// [utest->R-037] the `asyncapi` field rides the same parser-free read
+	expect(lockfile.services.svc.specVersion).toBe("3.0.0");
 	expect(warnings).toHaveLength(1);
 	expect(warnings[0]).toContain("branch tip 'main'"); // honesty warning names the branch
 
@@ -161,6 +163,53 @@ test("resolveServices resolves all services (bounded), warns per branch, builds
 	expect(yaml).not.toContain("resolvedSha"); // not camelCase
 });
 
+// [utest->R-037]
+test("the lockfile records the AsyncAPI spec version beside the declared version", () => {
+	const lock = serializeLockfile({
+		lockfileVersion: 1,
+		environment: "default",
+		resolutionMode: "branch",
+		generatedAt: "2026-07-30T00:00:00.000Z",
+		services: {
+			svc: {
+				requestedVersion: "1.0.0",
+				resolutionStrategy: "branch",
+				resolvedRef: "main",
+				resolvedSha: "0".repeat(40),
+				specPath: "asyncapi.yaml",
+				declaredVersion: "4.2.0",
+				specVersion: "3.1.0",
+				contentHash: "sha256:abc",
+				fetchedAt: "2026-07-30T00:00:00.000Z",
+			},
+		},
+	});
+	expect(lock).toContain("spec-version: 3.1.0");
+	expect(lock).toContain("declared-version: 4.2.0");
+});
+
+// [utest->R-037]
+test("spec-version is omitted when the asyncapi field is unreadable", () => {
+	const lock = serializeLockfile({
+		lockfileVersion: 1,
+		environment: "default",
+		resolutionMode: "branch",
+		generatedAt: "2026-07-30T00:00:00.000Z",
+		services: {
+			svc: {
+				requestedVersion: "1.0.0",
+				resolutionStrategy: "branch",
+				resolvedRef: "main",
+				resolvedSha: "0".repeat(40),
+				specPath: "asyncapi.yaml",
+				contentHash: "sha256:abc",
+				fetchedAt: "2026-07-30T00:00:00.000Z",
+			},
+		},
+	});
+	expect(lock).not.toContain("spec-version");
+});
+
 test("ingestion/ imports no @asyncapi/parser (G12 — parser-free)", async () => {
 	const src = await Bun.file(`${import.meta.dir}/index.ts`).text();
 	// guard the import edge, not mentions of the name in prose comments
diff --git a/src/ingestion/index.ts b/src/ingestion/index.ts
index 63bc090..37fd60a 100644
--- a/src/ingestion/index.ts
+++ b/src/ingestion/index.ts
@@ -11,6 +11,7 @@ import type {
 	ServiceConfig,
 	VersionSource,
 } from "#src/model/index.ts";
+import { readSpecVersion } from "#src/model/spec-version.ts";
 
 // ingestion/ imports NO @asyncapi/parser (G12). It shells out to `git` for fetch, and uses `yaml`
 // only for (a) a shallow info.version read of the fetched spec and (b) serializing the lockfile.
@@ -155,6 +156,7 @@ export class GitRefResolver implements Resolver {
 				resolvedSha,
 				source: `${ref}@${repo}:${specPath}`, // keeps the authored repo form (slug or URL)
 				declaredVersion: readDeclaredVersion(content),
+				specVersion: readSpecVersion(content),
 				fetchedAt: new Date().toISOString(),
 			};
 		} finally {
@@ -190,6 +192,7 @@ export function buildLockEntry(
 		resolvedSha: resolved.resolvedSha,
 		specPath: resolved.specPath,
 		declaredVersion: resolved.declaredVersion,
+		specVersion: resolved.specVersion,
 		contentHash: resolved.contentHash,
 		fetchedAt: resolved.fetchedAt,
 	};
@@ -215,6 +218,9 @@ export function serializeLockfile(lock: Lockfile): string {
 					...(e.declaredVersion !== undefined
 						? { "declared-version": e.declaredVersion }
 						: {}),
+					...(e.specVersion !== undefined
+						? { "spec-version": e.specVersion }
+						: {}),
 					"content-hash": e.contentHash,
 					"fetched-at": e.fetchedAt,
 				},
diff --git a/src/model/index.ts b/src/model/index.ts
index 5e7f4ea..b876c22 100644
--- a/src/model/index.ts
+++ b/src/model/index.ts
@@ -38,6 +38,13 @@ export interface SpecRegistry {
 	): { channel: Channel; params: Record<string, string> } | undefined;
 	matchesFilter(filter: string, topic: string): boolean;
 	channels(): readonly Channel[];
+	// Registry-time spec-QUALITY findings (D-018): problems discoverable only
+	// while building the catalog, so they cannot be recomputed from Channel
+	// later (binding placement, dialect mismatch, a schema that would not
+	// compile). Collected once at build; the composition root merges them into
+	// GET /v1/diagnostics beside the computed ones. Uses the existing closed
+	// `spec-load` kind with a machine-greppable `detail` tag prefix.
+	diagnostics(): readonly Diagnostic[];
 }
 
 export interface Config {
@@ -98,6 +105,7 @@ export interface ResolvedSpec {
 	resolvedSha: string; // FULL canonical commit sha — the pin, never abbreviated
 	source: string; // human origin, e.g. "dev@org/service-b:asyncapi.yaml"
 	declaredVersion?: string; // info.version — shallow parser-free read by ingestion/ (G12); best-effort
+	specVersion?: string; // the `asyncapi` version — shallow parser-free read (G12); best-effort
 	fetchedAt: string; // ISO8601
 }
 
@@ -126,6 +134,7 @@ export interface LockEntry {
 	resolvedSha: string; // FULL canonical commit sha — never abbreviated
 	specPath: string;
 	declaredVersion?: string; // info.version
+	specVersion?: string; // the `asyncapi` version of the fetched spec
 	contentHash: string; // "sha256:…"
 	fetchedAt: string; // ISO8601
 	resolvedVersion?: string; // v2 only — semver after range policy
@@ -243,6 +252,7 @@ export interface EmitStep {
 export interface SpecInfo {
 	service: string;
 	declaredVersion?: string; // info.version — parser-free shallow read by ingestion/ (G12); NOT requested
+	specVersion?: string; // the `asyncapi` version — which spec major this service is on
 	source: string;
 	contentHash: string;
 	channelCount: number;
diff --git a/src/model/spec-version.test.ts b/src/model/spec-version.test.ts
new file mode 100644
index 0000000..21b371d
--- /dev/null
+++ b/src/model/spec-version.test.ts
@@ -0,0 +1,61 @@
+// [utest->R-037]
+import { expect, test } from "bun:test";
+import {
+	SUPPORTED_SPEC_VERSIONS,
+	isSupportedSpecVersion,
+	readSpecVersion,
+} from "./spec-version.ts";
+
+test("reads the asyncapi version from spec text without a parser", () => {
+	expect(
+		readSpecVersion("asyncapi: 3.0.0\ninfo: { title: T, version: 1.0.0 }"),
+	).toBe("3.0.0");
+	expect(
+		readSpecVersion("asyncapi: '2.6.0'\ninfo: { title: T, version: 1.0.0 }"),
+	).toBe("2.6.0");
+});
+
+test("a YAML-numeric version is normalized to a string", () => {
+	// `asyncapi: 2.6` is a YAML float, not a string; String() keeps the read honest
+	expect(readSpecVersion("asyncapi: 2.6")).toBe("2.6");
+});
+
+test("absent or unparseable spec text yields undefined, never a throw", () => {
+	expect(readSpecVersion("info: { title: T }")).toBeUndefined();
+	expect(readSpecVersion("this: [is: not: valid: yaml")).toBeUndefined();
+	expect(readSpecVersion("")).toBeUndefined();
+});
+
+// [utest->R-037]
+test('a present-but-null asyncapi field reads as the string "null", not undefined', () => {
+	// `asyncapi:` with no value is a genuinely PRESENT field (YAML null), distinct
+	// from the field being absent. Collapsing it to undefined let the preflight
+	// fall through to the parser, which TypeErrors on it (D-019); reading it as
+	// "null" instead routes it into the preflight's own branded refusal.
+	expect(readSpecVersion("asyncapi:\ninfo: { title: T, version: 1.0.0 }")).toBe(
+		"null",
+	);
+});
+
+test("the supported set is exactly the tested promise (2.0.0-2.6.0, 3.0.0, 3.1.0)", () => {
+	expect([...SUPPORTED_SPEC_VERSIONS]).toEqual([
+		"2.0.0",
+		"2.1.0",
+		"2.2.0",
+		"2.3.0",
+		"2.4.0",
+		"2.5.0",
+		"2.6.0",
+		"3.0.0",
+		"3.1.0",
+	]);
+});
+
+test("1.x, the 2.0.0 release candidates, and absent versions are unsupported", () => {
+	expect(isSupportedSpecVersion("3.1.0")).toBe(true);
+	expect(isSupportedSpecVersion("2.0.0")).toBe(true);
+	expect(isSupportedSpecVersion("1.2.0")).toBe(false);
+	expect(isSupportedSpecVersion("2.0.0-rc1")).toBe(false);
+	expect(isSupportedSpecVersion("4.0.0")).toBe(false);
+	expect(isSupportedSpecVersion(undefined)).toBe(false);
+});
diff --git a/src/model/spec-version.ts b/src/model/spec-version.ts
new file mode 100644
index 0000000..d00facf
--- /dev/null
+++ b/src/model/spec-version.ts
@@ -0,0 +1,50 @@
+// R-037 — the AsyncAPI version contract plus a parser-free shallow read of the
+// `asyncapi` field. Tier 0 (model): pure functions over raw text, so both
+// `registry/` (the preflight gate) and `ingestion/` (lockfile provenance, G12)
+// can use them without a cross-import between tier-1 peers.
+import { parse as parseYaml } from "yaml";
+
+// The versions offbook PROMISES and TESTS. Deliberately an explicit list rather
+// than `Object.keys(specs.schemas)`: the parser derives its accepted set from
+// whatever @asyncapi/specs resolves at install time, so a schema being present
+// does NOT mean the parser's ruleset handles that version. Parser 3.4.0 and
+// 3.5.0 accept a 3.1.0 document past their version gate and then die inside
+// Spectral with "Error running Nimma". See D-018.
+export const SUPPORTED_SPEC_VERSIONS = [
+	"2.0.0",
+	"2.1.0",
+	"2.2.0",
+	"2.3.0",
+	"2.4.0",
+	"2.5.0",
+	"2.6.0",
+	"3.0.0",
+	"3.1.0",
+] as const;
+
+// Best-effort, mirroring ingestion's readDeclaredVersion (G12): no
+// @asyncapi/parser, no schema interpretation. A spec that will not yaml-parse,
+// or that has no `asyncapi` field, just yields undefined.
+export function readSpecVersion(specText: string): string | undefined {
+	try {
+		const doc = parseYaml(specText) as { asyncapi?: unknown } | null;
+		const v = doc?.asyncapi;
+		// undefined ONLY for a genuinely absent field. A present-but-null value
+		// (bare `asyncapi:`) reads as the string "null" and is therefore a
+		// positive read: it falls into the preflight's branded refusal instead
+		// of past it into the parser's raw TypeError. String() stays broad
+		// (never narrowed to string/number) because the parser's internal
+		// TypeError also fires on `''`, `true`, and `{}` — every one of those
+		// must land here as a positive read too (D-019).
+		return v === undefined ? undefined : String(v);
+	} catch {
+		return undefined;
+	}
+}
+
+export function isSupportedSpecVersion(v: string | undefined): boolean {
+	return (
+		v !== undefined &&
+		(SUPPORTED_SPEC_VERSIONS as readonly string[]).includes(v)
+	);
+}
diff --git a/src/registry/index.test.ts b/src/registry/index.test.ts
index 3e771ae..fdfa2bb 100644
--- a/src/registry/index.test.ts
+++ b/src/registry/index.test.ts
@@ -1,7 +1,8 @@
 import { expect, test } from "bun:test";
 import { readdirSync } from "node:fs";
 import { loadConfig, loadServices } from "#src/config/index.ts";
-import type { ServiceConfig } from "#src/model/index.ts";
+import { DEFAULT_CONFIG, type ServiceConfig } from "#src/model/index.ts";
+import { SUPPORTED_SPEC_VERSIONS } from "#src/model/spec-version.ts";
 import { buildRegistry } from "./index.ts";
 
 // [utest->R-004]
@@ -169,7 +170,7 @@ test("composition: validates allOf+oneOf on BOTH the toClient and fromClient pat
 	expect((submissions?.validate(bad) ?? []).length).toBeGreaterThan(0);
 });
 
-test("external-ref: bundles a cross-file $ref (+$id base) into an Ajv-2020 standalone schema", async () => {
+test("external-ref: bundles a cross-file $ref (+$id base) into an Ajv standalone schema", async () => {
 	const ch = (await registryFor("external-ref.yaml")).match(
 		"telemetry/node-1",
 	)?.channel;
@@ -186,13 +187,14 @@ test("external-ref: bundles a cross-file $ref (+$id base) into an Ajv-2020 stand
 	).toBeGreaterThan(0);
 });
 
-test("external-ref: KNOWN LIMITATION (D-005, §12.4) — a $ref-sibling keyword under 2020-12 is dropped", async () => {
+test("external-ref: a $ref-sibling keyword is not enforced, which is draft-07-correct (D-018)", async () => {
 	const ch = (await registryFor("external-ref.yaml")).match(
 		"telemetry/node-1",
 	)?.channel;
-	// nodeId carries `minLength: 3` as a $ref sibling. @asyncapi/parser normalizes to draft-07,
-	// which drops $ref siblings — so a 2-char (pattern-valid) id is WRONGLY accepted. This test
-	// pins that limitation; it flips red when the 2020-12 schema-parser spike lands (revisit D-005).
+	// nodeId carries `minLength: 3` as a $ref sibling. draft-07 ignores $ref siblings, and it is
+	// the dialect both spec majors declare and the parser emits, so a 2-char (pattern-valid) id is
+	// accepted BY DESIGN rather than by accident (D-018 supersedes D-005's deferred spike). Pinned
+	// so that a future dialect change, which would start enforcing it, is loud.
 	expect(
 		ch?.validate({
 			nodeId: "ab",
@@ -201,3 +203,510 @@ test("external-ref: KNOWN LIMITATION (D-005, §12.4) — a $ref-sibling keyword
 		}),
 	).toEqual([]);
 });
+
+// [utest->R-037]
+test("refuses a 1.x spec with an actionable, branded error", async () => {
+	const spec = `asyncapi: '1.2.0'
+info: { title: Legacy, version: 1.0.0 }
+topics:
+  t.one:
+    publish:
+      payload: { type: object }
+`;
+	const attempt = buildRegistry({
+		specText: spec,
+		service: "legacy",
+		config: DEFAULT_CONFIG,
+	});
+	await expect(attempt).rejects.toThrow(
+		/unsupported AsyncAPI version "1\.2\.0"/,
+	);
+	// names EVERY tested version and the remedy, not just the problem. Built from
+	// the constant, so the assertion cannot drift from what the message renders.
+	for (const v of SUPPORTED_SPEC_VERSIONS) {
+		await expect(attempt).rejects.toThrow(v);
+	}
+	await expect(attempt).rejects.toThrow(/asyncapi convert/);
+});
+
+// [utest->R-037]
+test("a malformed spec surfaces the parser's own diagnostics, not a version error", async () => {
+	// A YAML syntax error is not a version problem, and `asyncapi convert` is not
+	// its remedy. Spec-load failure is fatal and aborts `up` (design §7 Mode 1),
+	// so this message is the whole error an adopter sees (R-036, D-019).
+	// `Promise.catch` unions its handler's return with the promise's own resolve
+	// type (here `SpecRegistry`), so `as Error` is a compile-time-only cast: it
+	// tells the type-checker what the rejection actually is without touching the
+	// runtime value.
+	const err = (await buildRegistry({
+		specText: "asyncapi: 3.0.0\ninfo: {title: T\n  bad indent: ][",
+		service: "svc-a",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error)) as Error;
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/failed to parse spec/);
+	expect(err.message).toMatch(/flow/); // the parser's own YAML syntax wording
+	expect(err.message).not.toMatch(/unsupported AsyncAPI version/);
+	expect(err.message).not.toMatch(/asyncapi convert/);
+});
+
+// [utest->R-037]
+test("an unquoted `asyncapi: 2.6` is refused before the parser's TypeError", async () => {
+	// `asyncapi: 2.6` is a YAML float, not a string, and the parser dies on it
+	// inside getSemver with a raw `patchWithRc.split` TypeError stack. The gate
+	// catches it first because String(2.6) is "2.6", which is not a tested
+	// version. This is why readSpecVersion normalizes with String() (D-019).
+	const err = (await buildRegistry({
+		specText: "asyncapi: 2.6\ninfo: { title: T, version: 1.0.0 }\nchannels: {}",
+		service: "floaty",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error)) as Error;
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/unsupported AsyncAPI version "2\.6"/);
+	expect(err.message).not.toMatch(/patchWithRc/);
+});
+
+// [utest->R-037]
+test("a present-but-null `asyncapi:` is refused with the branded message, not the parser's raw TypeError", async () => {
+	// `asyncapi:` with no value is a YAML null: a PRESENT field, distinct from an
+	// absent one. Before D-019's fix this collapsed to undefined, fell through
+	// the preflight, and reached @asyncapi/parser, which TypeErrors on it
+	// (`patchWithRc.split`) with a raw internal stack instead of an actionable
+	// message.
+	const err = (await buildRegistry({
+		specText: "asyncapi:\ninfo: { title: T, version: 1.0.0 }\nchannels: {}",
+		service: "nullver",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error)) as Error;
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/unsupported AsyncAPI version "null"/);
+	expect(err.message).not.toMatch(/patchWithRc/);
+});
+
+// [utest->R-037]
+test("a version inside the old range but outside the tested set is still refused", async () => {
+	// 2.7.0 sits INSIDE "2.0.0 through 3.1.0" while being untested, which is
+	// exactly why the message names the set instead of a range (D-019).
+	const err = (await buildRegistry({
+		specText:
+			"asyncapi: '2.7.0'\ninfo: { title: T, version: 1.0.0 }\nchannels: {}",
+		service: "future",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error)) as Error;
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/unsupported AsyncAPI version "2\.7\.0"/);
+	expect(err.message).not.toMatch(/through/);
+});
+
+// [utest->R-037]
+test("a spec with no asyncapi field defers to the parser's diagnosis", async () => {
+	// Not offbook's call to make: the parser names the real problem precisely,
+	// and guessing "unsupported version" here mislabels an empty file, an HTML
+	// error page from a bad repo URL, and a wrong spec-path alike (D-019).
+	const err = (await buildRegistry({
+		specText: "info: { title: T, version: 1.0.0 }",
+		service: "nover",
+		config: DEFAULT_CONFIG,
+	}).catch((e: unknown) => e as Error)) as Error;
+	expect(err).toBeInstanceOf(Error);
+	expect(err.message).toMatch(/failed to parse spec/);
+	expect(err.message).toMatch(/This is not an AsyncAPI document/);
+	expect(err.message).not.toMatch(/unsupported AsyncAPI version/);
+});
+
+// [utest->R-037]
+test("accepts every version in the supported contract", async () => {
+	for (const v of SUPPORTED_SPEC_VERSIONS) {
+		const spec = v.startsWith("3.")
+			? `asyncapi: ${v}
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/one, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`
+			: `asyncapi: ${v}
+info: { title: T, version: 1.0.0 }
+channels:
+  t/one:
+    subscribe:
+      operationId: s
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+		const reg = await buildRegistry({
+			specText: spec,
+			service: "s",
+			config: DEFAULT_CONFIG,
+		});
+		expect(reg.channels().length, `version ${v} should yield one channel`).toBe(
+			1,
+		);
+	}
+});
+
+// [utest->R-038]
+test("a multi-format payload still VALIDATES (the wrapper must be unwrapped)", async () => {
+	const reg = await registryFor("multi-format.yaml");
+	const reading = reg.match("reading/s1")?.channel;
+	expect(reading).toBeDefined();
+	// the schema handed to Ajv must be the payload schema, not the wrapper
+	expect(Object.keys(reading?.schema as object)).not.toContain("schemaFormat");
+	expect(Object.keys(reading?.schema as object)).not.toContain("schema");
+	// conforming payload passes
+	expect(reading?.validate({ sensorId: "s1", celsius: 21.5 })).toEqual([]);
+	// and the tripwire: garbage must NOT pass. Before the unwrap every one of
+	// these validated green, which is the false-negative class R-028 forbids.
+	expect(
+		reading?.validate({ sensorId: 42, celsius: "hot" }).length,
+	).toBeGreaterThan(0);
+	expect(reading?.validate({ unrelated: true }).length).toBeGreaterThan(0);
+	expect(reading?.validate("not-an-object").length).toBeGreaterThan(0);
+	expect(reading?.validate(null).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("the multi-format wrapper is unwrapped on the client-publish path too", async () => {
+	const reg = await registryFor("multi-format.yaml");
+	const calibrate = reg.match("calibrate/s1")?.channel;
+	expect(calibrate?.direction).toBe("fromClient");
+	expect(calibrate?.validate({ offset: 0.5 })).toEqual([]);
+	expect(calibrate?.validate({ offset: "half" }).length).toBeGreaterThan(0);
+	expect(calibrate?.validate({}).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+// Inline rather than a fixture on purpose: json-schema-faker 0.6.2 cannot draw a
+// valid draft-07 tuple (it emits objects with numeric keys, e.g.
+// [{"0":"ab","1":1.5}], failing the Ajv recheck 10/10 regardless of
+// additionalItems or minItems). A tuple channel in fixtures/asyncapi/ would
+// therefore fail the R-027 faker-floor spike and flip D-008's measured verdict,
+// which is a separate question from the dialect this test pins. See D-018.
+test("draft-07 tuple `items` validates positionally instead of crashing the build", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: window/{sensorId}
+    parameters:
+      sensorId:
+        description: sensor instance id
+    messages:
+      Window:
+        payload:
+          type: array
+          items:
+            - type: string
+            - type: number
+          additionalItems: false
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	// under the old 2020-12 stamp this THREW out of buildRegistry, uncaught
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const window = reg.match("window/s1")?.channel;
+	expect(window).toBeDefined();
+	expect(window?.validate(["a", 1])).toEqual([]);
+	// wrong order and wrong type at position 1 are both caught
+	expect(window?.validate([1, "a"]).length).toBeGreaterThan(0);
+	expect(window?.validate(["a", "b"]).length).toBeGreaterThan(0);
+	// additionalItems: false is honored under draft-07 (2020-12 ignores it)
+	expect(window?.validate(["a", 1, "extra"]).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("channel schemas declare the draft-07 dialect they are validated under", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	const schema = reg.channels()[0].schema as { $schema?: string };
+	expect(schema.$schema).toBe("http://json-schema.org/draft-07/schema#");
+});
+
+// [utest->R-039]
+test("an mqtt CHANNEL binding is reported as ignored, not silently dropped", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/chanbound
+    bindings: { mqtt: { qos: 2, retain: true } }
+    messages: { M: { payload: { type: object, properties: { a: { type: string } } } } }
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	// MQTT defines qos/retain on the OPERATION only: the Channel Binding Object
+	// "MUST NOT contain any properties" at every binding version, so the values
+	// are ignored and the channel keeps the global defaults.
+	expect(reg.match("t/chanbound")?.channel.qos).toBe(1);
+	const found = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("binding-on-channel:"));
+	expect(found.length).toBe(1);
+	expect(found[0].kind).toBe("spec-load");
+	expect(found[0].severity).toBe("warning");
+	expect(found[0].source).toBe("t/chanbound");
+});
+
+// [utest->R-039]
+test("a clean spec produces no registry diagnostics", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	expect(reg.diagnostics()).toEqual([]);
+});
+
+// [utest->R-038]
+test("post-draft-07 keywords are surfaced, since draft-07 ignores them silently", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/modern
+    messages:
+      M:
+        payload:
+          type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              prefixItems:
+                - type: string
+          unevaluatedProperties: false
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const found = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("dialect-mismatch:"));
+	expect(found.length).toBe(1);
+	expect(found[0].severity).toBe("warning");
+	expect(found[0].source).toBe("t/modern");
+	// names every offending keyword so the author can fix them all at once
+	expect(found[0].detail).toContain("prefixItems");
+	expect(found[0].detail).toContain("unevaluatedProperties");
+});
+
+// [utest->R-038]
+test("$defs and definitions are NOT reported: both work under draft-07", async () => {
+	// the repo's own shared/common.yaml uses $defs, so flagging it would cry wolf
+	const reg = await registryFor("external-ref.yaml");
+	expect(
+		reg.diagnostics().filter((d) => d.detail.startsWith("dialect-mismatch:")),
+	).toEqual([]);
+});
+
+// [utest->R-038]
+test("a schema that will not compile yields violations, never a crash and never green", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c:
+    address: t/broken
+    messages:
+      M:
+        payload:
+          type: object
+          properties:
+            bad:
+              type: string
+              pattern: '['
+operations:
+  o: { action: send, channel: { $ref: '#/channels/c' } }
+`;
+	// does not throw: discovery is a v1 floor that must survive a weak spec
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const broken = reg.match("t/broken")?.channel;
+	expect(broken).toBeDefined();
+	// and it must NOT validate green, which would be false confidence
+	const errs = broken?.validate({ anything: true }) ?? [];
+	expect(errs.length).toBe(1);
+	expect(errs[0].keyword).toBe("offbook:schema-compile-failed");
+	const found = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("schema-compile-failed:"));
+	expect(found.length).toBe(1);
+	expect(found[0].severity).toBe("error");
+	expect(found[0].source).toBe("t/broken");
+});
+
+// [utest->R-038]
+test("a v2 message.oneOf union validates EITHER variant, not just the first", async () => {
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/union:
+    subscribe:
+      operationId: s
+      message:
+        oneOf:
+          - payload: { type: object, required: [a], additionalProperties: false, properties: { a: { type: string } } }
+          - payload: { type: object, required: [b], additionalProperties: false, properties: { b: { type: number } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const union = reg.match("t/union")?.channel;
+	expect(union?.validate({ a: "x" })).toEqual([]);
+	// before the anyOf, variant two was reported as a violation because only
+	// messages()[0] was read
+	expect(union?.validate({ b: 2 })).toEqual([]);
+	// and something matching NEITHER variant is still caught
+	expect(union?.validate({ c: true }).length).toBeGreaterThan(0);
+});
+
+// [utest->R-038]
+test("a single-message operation keeps its schema unwrapped by anyOf", async () => {
+	const reg = await registryFor("thermostat.yaml");
+	const schema = reg.channels()[0].schema as Record<string, unknown>;
+	expect(schema.anyOf).toBeUndefined();
+	expect(schema.type).toBe("object");
+});
+
+// [utest->R-039]
+test("the oldest supported major parses, inverts direction, and its binding is read", async () => {
+	const reg = await registryFor("v2-oldest.yaml");
+	const telemetry = reg.match("legacy/d1/telemetry")?.channel;
+	const command = reg.match("legacy/d1/command")?.channel;
+	// v2 subscribe = messages PRODUCED by the application (the service) ⇒ toClient
+	expect(telemetry?.direction).toBe("toClient");
+	// v2 publish = messages CONSUMED by the application ⇒ the client sends them
+	expect(command?.direction).toBe("fromClient");
+	expect(telemetry?.qos).toBe(2);
+	expect(telemetry?.retain).toBe(true);
+	expect(reg.diagnostics()).toEqual([]);
+});
+
+// [utest->R-039]
+test("an out-of-range binding qos is rejected and falls through the precedence chain", async () => {
+	// 2.x maps `mqtt` to an empty schema, so qos 9 parses clean upstream and
+	// would otherwise reach a Channel typed 0 | 1 | 2
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/bad:
+    subscribe:
+      operationId: s
+      bindings:
+        mqtt: { qos: 9, retain: "yes" }
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+		serviceConfig: {
+			name: "s",
+			repo: "x",
+			specPath: "y",
+			qosDefault: 0,
+			retainDefault: true,
+		},
+	});
+	const ch = reg.match("t/bad")?.channel;
+	// falls through to the per-service default (tier 3), NOT clamped and NOT propagated
+	expect(ch?.qos).toBe(0);
+	expect(ch?.retain).toBe(true);
+	const bad = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("binding-invalid-value:"));
+	expect(bad.length).toBe(2);
+	expect(bad.every((d) => d.severity === "warning")).toBe(true);
+});
+
+// [utest->R-039]
+test("a misspelled binding key is reported against the official key set", async () => {
+	const spec = `asyncapi: 2.6.0
+info: { title: T, version: 1.0.0 }
+channels:
+  t/typo:
+    subscribe:
+      operationId: s
+      bindings:
+        mqtt: { qos: 1, retian: true }
+      message:
+        payload: { type: object, properties: { a: { type: string } } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const unknown = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("binding-unknown-key:"));
+	expect(unknown.length).toBe(1);
+	expect(unknown[0].detail).toContain("retian");
+});
+
+// [utest->R-039]
+test("MQTT-5-only binding fields are reported as unhonored", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/five, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o:
+    action: send
+    channel: { $ref: '#/channels/c' }
+    bindings: { mqtt: { qos: 1, messageExpiryInterval: 60 } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	const five = reg
+		.diagnostics()
+		.filter((d) => d.detail.startsWith("mqtt5-field-ignored:"));
+	expect(five.length).toBe(1);
+	expect(five[0].detail).toContain("messageExpiryInterval");
+	expect(five[0].severity).toBe("info");
+});
+
+// [utest->R-039]
+test("a vendor extension key on an mqtt binding is legal, not an unknown key", async () => {
+	const spec = `asyncapi: 3.0.0
+info: { title: T, version: 1.0.0 }
+channels:
+  c: { address: t/ext, messages: { M: { payload: { type: object, properties: { a: { type: string } } } } } }
+operations:
+  o:
+    action: send
+    channel: { $ref: '#/channels/c' }
+    bindings: { mqtt: { qos: 2, x-vendor-thing: true } }
+`;
+	const reg = await buildRegistry({
+		specText: spec,
+		service: "s",
+		config: DEFAULT_CONFIG,
+	});
+	// the official binding schema permits ^x-[\w\d\.\x2d_]+$ via patternProperties,
+	// which the derived key set ignored because it read only `properties` (D-019)
+	expect(
+		reg
+			.diagnostics()
+			.filter((d) => d.detail.startsWith("binding-unknown-key:")),
+	).toEqual([]);
+	// and the legal fields on the same binding still take effect: qos 2 differs
+	// from the global default of 1, so this assertion is not vacuous
+	expect(reg.match("t/ext")?.channel.qos).toBe(2);
+});
diff --git a/src/registry/index.ts b/src/registry/index.ts
index d7eca50..cf4a978 100644
--- a/src/registry/index.ts
+++ b/src/registry/index.ts
@@ -1,14 +1,20 @@
 import { Parser } from "@asyncapi/parser";
+import Ajv from "ajv";
 import addFormats from "ajv-formats";
-import Ajv2020 from "ajv/dist/2020";
 import { exec, matches } from "mqtt-pattern";
 import type {
 	Channel,
 	Config,
+	Diagnostic,
 	SchemaError,
 	ServiceConfig,
 	SpecRegistry,
 } from "#src/model/index.ts";
+import {
+	SUPPORTED_SPEC_VERSIONS,
+	isSupportedSpecVersion,
+	readSpecVersion,
+} from "#src/model/spec-version.ts";
 
 const parser = new Parser();
 
@@ -25,6 +31,104 @@ function directionOf(action: string): "toClient" | "fromClient" {
 		: "fromClient";
 }
 
+// AsyncAPI 3.x lets a payload be a Multi Format Schema Object (`{schemaFormat,
+// schema}`), permitted even for the default JSON-Schema format. `BaseModel.json()`
+// returns that wrapper verbatim (the parser's own Schema model unwraps
+// `_json.schema` internally for its typed accessors), so spreading it yields a
+// schema with NO validation keywords: a validator that accepts everything (D-018).
+// Deliberately does NOT branch on the schemaFormat STRING: the implementation
+// emits `application/vnd.aai.asyncapi;version=X` while the spec text mandates a
+// `+json` suffix, so a literal comparison would silently stop matching.
+function extractPayloadSchema(payloadJson: unknown): object {
+	if (payloadJson === null || typeof payloadJson !== "object") return {};
+	const p = payloadJson as Record<string, unknown>;
+	if (
+		"schemaFormat" in p &&
+		typeof p.schema === "object" &&
+		p.schema !== null
+	) {
+		return p.schema as object;
+	}
+	return p;
+}
+
+// The dialect BOTH spec majors declare for the Schema Object ("a superset of
+// JSON Schema Draft 07") and the one @asyncapi/parser actually emits. Stamping
+// 2020-12 over it was the root cause of the tuple-compile crash and of
+// `additionalItems` being silently ignored (D-018). Stamped explicitly so
+// `channel.schema`, which GET /topics hands out, is self-describing.
+const DRAFT_07 = "http://json-schema.org/draft-07/schema#";
+
+// Keywords JSON Schema introduced after draft-07. offbook validates under
+// draft-07, where these are unknown and therefore SILENTLY IGNORED, which is
+// the worst failure mode for a contract checker, so their presence is surfaced
+// (D-018). `$defs` and `definitions` are deliberately absent: both resolve
+// correctly under draft-07, and fixtures/asyncapi/shared/common.yaml
+// legitimately uses `$defs`.
+const POST_DRAFT07_KEYWORDS = new Set([
+	"prefixItems",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"dependentRequired",
+	"dependentSchemas",
+	"minContains",
+	"maxContains",
+	"$dynamicRef",
+	"$dynamicAnchor",
+	"$recursiveRef",
+	"$recursiveAnchor",
+]);
+
+// The mqtt OPERATION binding's legal keys, transcribed from @asyncapi/specs'
+// bindings/mqtt/0.2.0/operation.json. Hand-authored and drift-tested rather than
+// derived at runtime, for the reason D-018 gave for SUPPORTED_SPEC_VERSIONS: a
+// value being present upstream is not the same as offbook having tested it.
+// Keeping it a constant is also what lets @asyncapi/specs be a devDependency
+// (D-019) instead of an undeclared transitive of @asyncapi/parser, resolved only
+// by flat hoisting. Validating against 0.2.0 is permissive-correct: its property
+// set is a superset of 0.1.0's. Exported for test/upstream-drift.test.ts, which
+// pins both halves against the installed schema.
+export const MQTT_OPERATION_KEYS = new Set([
+	"bindingVersion",
+	"messageExpiryInterval",
+	"qos",
+	"retain",
+]);
+
+// The same schema permits vendor extensions via `patternProperties`. Transcribed
+// character-for-character from that key, so the drift test compares source
+// strings rather than approximating the intent. Reading only `properties` meant
+// a spec-legal `x-vendor-thing` was reported as an unknown key (D-019).
+export const MQTT_EXTENSION_KEY = /^x-[\w\d\.\x2d_]+$/;
+
+// MQTT 5 only, per the "MQTT Versions" column of the binding spec. offbook is
+// MQTT 3.1.1 only, so these can never be honored and saying so beats silence.
+const MQTT5_ONLY_KEYS = new Set([
+	"messageExpiryInterval",
+	"payloadFormatIndicator",
+	"correlationData",
+	"contentType",
+	"responseTopic",
+	"sessionExpiryInterval",
+	"maximumPacketSize",
+]);
+
+function postDraft07Keywords(
+	node: unknown,
+	found: Set<string> = new Set(),
+): Set<string> {
+	if (Array.isArray(node)) {
+		for (const item of node) postDraft07Keywords(item, found);
+		return found;
+	}
+	if (node === null || typeof node !== "object") return found;
+	for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+		if (POST_DRAFT07_KEYWORDS.has(key)) found.add(key);
+		postDraft07Keywords(value, found);
+	}
+	return found;
+}
+
 export async function buildRegistry(opts: {
 	specText: string;
 	service: string;
@@ -34,6 +138,28 @@ export async function buildRegistry(opts: {
 	// base path/URI so the parser can resolve external $refs (e.g. shared/common.yaml); omit for self-contained specs
 	source?: string;
 }): Promise<SpecRegistry> {
+	// R-037 preflight: check the declared version BEFORE handing the document to
+	// the parser. The parser's own gate is derived from @asyncapi/specs at
+	// install time, so an unsupported-but-present version can pass it and then
+	// fail deep in the Spectral ruleset with an opaque "Error running Nimma"
+	// (D-018) — or, for an unquoted `asyncapi: 2.6`, with a raw TypeError stack
+	// out of getSemver.
+	//
+	// Fires ONLY on a version this read positively resolved. An unreadable or
+	// absent `asyncapi` field is not offbook's call to make: the parser's own
+	// diagnostics distinguish a YAML syntax error from a non-AsyncAPI document,
+	// and guessing "unsupported version" mislabelled both, along with the empty
+	// file and the fetched HTML error page (D-019). The message names the tested
+	// set rather than a range, because a version can sit inside 2.0.0-3.1.0 and
+	// still be untested.
+	const specVersion = readSpecVersion(opts.specText);
+	if (specVersion !== undefined && !isSupportedSpecVersion(specVersion)) {
+		throw new Error(
+			`unsupported AsyncAPI version "${specVersion}" in service '${opts.service}': offbook supports ${SUPPORTED_SPEC_VERSIONS.join(
+				", ",
+			)}. Convert the spec first: \`asyncapi convert <file> --target-version 3.1.0\``,
+		);
+	}
 	const parsed = opts.source
 		? await parser.parse(opts.specText, { source: opts.source })
 		: await parser.parse(opts.specText);
@@ -44,30 +170,145 @@ export async function buildRegistry(opts: {
 			.map((d) => d.message);
 		throw new Error(`failed to parse spec: ${errs.join("; ")}`);
 	}
-	const ajv = addFormats(new Ajv2020({ allErrors: true, strict: false }));
+	const ajv = addFormats(new Ajv({ allErrors: true, strict: false }));
 
 	const channels: Channel[] = [];
+	const diagnostics: Diagnostic[] = [];
 	for (const op of document.operations().all()) {
 		const ch = op.channels().all()[0];
 		const address = ch.address() ?? "";
-		const msg = op.messages().all()[0];
-		const schema = {
-			$schema: "https://json-schema.org/draft/2020-12/schema",
-			...((msg?.payload()?.json() ?? {}) as object),
-		};
-		const validateFn = ajv.compile(schema);
-		const mqtt = op.bindings().get("mqtt")?.value<{
-			qos?: 0 | 1 | 2;
-			retain?: boolean;
-		}>();
+		// MQTT defines qos/retain on the OPERATION binding only: the Channel
+		// Binding Object "MUST NOT contain any properties. Its name is reserved
+		// for future use." at every binding version. A channel-level mqtt binding
+		// nonetheless parses clean, so say it is ignored rather than defaulting
+		// in silence (D-018).
+		const channelMqtt = ch
+			.bindings()
+			.get("mqtt")
+			?.value<Record<string, unknown>>();
+		if (channelMqtt && Object.keys(channelMqtt).length > 0) {
+			const keys = Object.keys(channelMqtt).join(", ");
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-on-channel: '${address}' declares an mqtt CHANNEL binding (${keys}); MQTT defines qos/retain on the operation only, so these are ignored`,
+				source: address,
+			});
+		}
+		// An MQTT topic can legitimately carry one of several declared message
+		// types (a v2 `message.oneOf` union, or a v3 operation listing several
+		// messages). Reading only messages()[0] reported every other variant as a
+		// violation. `anyOf` keeps Channel.schema singular, so the faker and
+		// /topics are unaffected (D-018).
+		const messages = op.messages().all();
+		const msg = messages[0];
+		const payloadSchemas = messages.map((m) =>
+			extractPayloadSchema(m.payload()?.json()),
+		);
+		const schema =
+			payloadSchemas.length > 1
+				? { $schema: DRAFT_07, anyOf: payloadSchemas }
+				: { $schema: DRAFT_07, ...(payloadSchemas[0] ?? {}) };
+		const modernKeywords = postDraft07Keywords(schema);
+		if (modernKeywords.size > 0) {
+			const names = [...modernKeywords].sort().join(", ");
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `dialect-mismatch: '${address}' uses post-draft-07 keyword(s) ${names}; offbook validates under draft-07 (the dialect both AsyncAPI majors declare), so these are NOT enforced`,
+				source: address,
+			});
+		}
+		// A schema Ajv refuses must never validate GREEN: that is false
+		// confidence, the failure mode this tool exists to prevent. The channel
+		// still enters the catalog because discovery is a v1 floor that survives
+		// weak specs, but every payload on it reports one explicit violation
+		// (D-018).
+		let validate: (payload: unknown) => SchemaError[];
+		try {
+			const validateFn = ajv.compile(schema);
+			validate = (payload: unknown): SchemaError[] =>
+				validateFn(payload) ? [] : ((validateFn.errors ?? []) as SchemaError[]);
+		} catch (cause) {
+			const reason = (cause as Error).message;
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "error",
+				detail: `schema-compile-failed: '${address}' payload schema did not compile, so nothing on this channel is validated: ${reason}`,
+				source: address,
+			});
+			const compileError: SchemaError = {
+				instancePath: "",
+				schemaPath: "#",
+				keyword: "offbook:schema-compile-failed",
+				params: {},
+				message: `payload schema did not compile: ${reason}`,
+			};
+			validate = () => [compileError];
+		}
+		// Read untyped: 2.x maps `mqtt` to an EMPTY schema in its own
+		// meta-schema, so nothing upstream validated these values and a declared
+		// type here would be a lie (D-018).
+		const mqtt = op.bindings().get("mqtt")?.value<Record<string, unknown>>();
+		if (mqtt) {
+			const unknownKeys = Object.keys(mqtt).filter(
+				(k) => !MQTT_OPERATION_KEYS.has(k) && !MQTT_EXTENSION_KEY.test(k),
+			);
+			if (unknownKeys.length > 0) {
+				const bad = unknownKeys.sort().join(", ");
+				const legal = [...MQTT_OPERATION_KEYS].sort().join(", ");
+				diagnostics.push({
+					kind: "spec-load",
+					severity: "warning",
+					detail: `binding-unknown-key: '${address}' mqtt operation binding has unknown key(s) ${bad}; the mqtt binding defines ${legal}`,
+					source: address,
+				});
+			}
+			const five = Object.keys(mqtt).filter((k) => MQTT5_ONLY_KEYS.has(k));
+			if (five.length > 0) {
+				const names = five.sort().join(", ");
+				diagnostics.push({
+					kind: "spec-load",
+					severity: "info",
+					detail: `mqtt5-field-ignored: '${address}' declares MQTT 5 binding field(s) ${names}; offbook speaks MQTT 3.1.1 only, so these are not honored`,
+					source: address,
+				});
+			}
+		}
+		const rawQos = mqtt?.qos;
+		const bindingQos =
+			rawQos === 0 || rawQos === 1 || rawQos === 2 ? rawQos : undefined;
+		if (rawQos !== undefined && bindingQos === undefined) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-invalid-value: '${address}' mqtt binding qos is ${JSON.stringify(
+					rawQos,
+				)}; qos MUST be 0, 1 or 2, so this binding is ignored and the configured default applies`,
+				source: address,
+			});
+		}
+		const rawRetain = mqtt?.retain;
+		const bindingRetain =
+			typeof rawRetain === "boolean" ? rawRetain : undefined;
+		if (rawRetain !== undefined && bindingRetain === undefined) {
+			diagnostics.push({
+				kind: "spec-load",
+				severity: "warning",
+				detail: `binding-invalid-value: '${address}' mqtt binding retain is ${JSON.stringify(
+					rawRetain,
+				)}; retain MUST be a boolean, so this binding is ignored and the configured default applies`,
+				source: address,
+			});
+		}
 		// §2 precedence, resolved per-field: spec MQTT binding → topicOverrides (tier 2,
 		// string-equality on the {param} address, F14) → per-service default (tier 3) → global.
 		// `??` (not `||`) so a legitimate qos 0 / retain false is not treated as "unset".
 		const override = opts.serviceConfig?.topicOverrides?.[address];
 		const qos =
-			mqtt?.qos ?? override?.qos ?? opts.serviceConfig?.qosDefault ?? 1;
+			bindingQos ?? override?.qos ?? opts.serviceConfig?.qosDefault ?? 1;
 		const retain =
-			mqtt?.retain ??
+			bindingRetain ??
 			override?.retain ??
 			opts.serviceConfig?.retainDefault ??
 			false;
@@ -76,8 +317,7 @@ export async function buildRegistry(opts: {
 			direction: directionOf(op.action()),
 			service: opts.service,
 			schema,
-			validate: (payload: unknown): SchemaError[] =>
-				validateFn(payload) ? [] : ((validateFn.errors ?? []) as SchemaError[]),
+			validate,
 			qos,
 			retain,
 			title: msg?.title() ?? undefined,
@@ -96,6 +336,7 @@ export async function buildRegistry(opts: {
 
 	return {
 		channels: () => channels,
+		diagnostics: () => diagnostics,
 		matchesFilter: (filter, topic) => matches(filter, topic),
 		match: (topic) => {
 			for (const { c } of ordered) {
@@ -122,6 +363,7 @@ export function mergeRegistries(registries: SpecRegistry[]): SpecRegistry {
 		});
 	return {
 		channels: () => channels,
+		diagnostics: () => registries.flatMap((r) => [...r.diagnostics()]),
 		matchesFilter: (filter, topic) => matches(filter, topic),
 		match: (topic) => {
 			for (const { c } of ordered) {
diff --git a/src/scenarios/index.test.ts b/src/scenarios/index.test.ts
index 0328b61..6130247 100644
--- a/src/scenarios/index.test.ts
+++ b/src/scenarios/index.test.ts
@@ -66,6 +66,7 @@ const channels = [
 ];
 
 const registry: SpecRegistry = {
+	diagnostics: () => [],
 	match(topic) {
 		for (const channel of channels) {
 			const params = matchTopic(channel.topic, topic);
diff --git a/src/scenarios/loader.test.ts b/src/scenarios/loader.test.ts
index acda922..93cde1c 100644
--- a/src/scenarios/loader.test.ts
+++ b/src/scenarios/loader.test.ts
@@ -57,6 +57,7 @@ const channels = [
 ];
 
 const registry: SpecRegistry = {
+	diagnostics: () => [],
 	match(topic) {
 		for (const channel of channels) {
 			const params = matchTopic(channel.topic, topic);
diff --git a/test/cli-dispatch.test.ts b/test/cli-dispatch.test.ts
index 1330d50..3b44e82 100644
--- a/test/cli-dispatch.test.ts
+++ b/test/cli-dispatch.test.ts
@@ -720,6 +720,7 @@ test("mergeRegistries: one registry over all services — most-specific wins acr
 			validate: () => [],
 		}) as unknown as Channel;
 	const regOf = (...channels: Channel[]): SpecRegistry => ({
+		diagnostics: () => [],
 		channels: () => channels,
 		match: () => undefined,
 		matchesFilter: () => false,
diff --git a/test/gate-validation.test.ts b/test/gate-validation.test.ts
index 9907878..7785929 100644
--- a/test/gate-validation.test.ts
+++ b/test/gate-validation.test.ts
@@ -1,14 +1,22 @@
 // R-028 — the §5 validation-correctness v1 gate, cross-cutting over the
-// module bars (R-004 registry, R-015 validation): the three named fixtures
+// module bars (R-004 registry, R-015 validation): the named fixtures
 // drive the COMPOSED stack end to end. A false negative (off-contract
 // payload passing green) or false positive (clean payload flagged) on any
 // of them is a tool-killer; qos-overrides also proves the tier-2/tier-3
 // config resolution reaches the wire (F14).
+//
+// multi-format and v2-oldest extend the gate across the SUPPORTED-VERSION
+// range (D-018): the newest major's explicit Multi Format Schema Object
+// payload and the oldest major's publish/subscribe form. Both shipped a
+// real false negative (a wrapper schema with no keywords accepted
+// everything; a 2.x binding validated by nothing reached a typed field),
+// so the composed-stack rejection of a known-bad payload on each is the
+// point of their entries here, not a unit-level detail.
 // [itest->R-028]
 import { afterEach, expect, test } from "bun:test";
 import { type Composed, compose } from "#src/compose/index.ts";
 import { loadConfig, loadServices } from "#src/config/index.ts";
-import type { StateEntry, Violation } from "#src/model/index.ts";
+import type { Direction, StateEntry, Violation } from "#src/model/index.ts";
 import { buildRegistry } from "#src/registry/index.ts";
 
 const FIXTURES = `${import.meta.dir}/../fixtures/asyncapi`;
@@ -48,7 +56,12 @@ async function bootFixture(
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify(body),
 			})
-		).json()) as { matched: boolean; injected: boolean; sinceSeq: number };
+		).json()) as {
+			direction: Direction | null;
+			matched: boolean;
+			injected: boolean;
+			sinceSeq: number;
+		};
 	const violationsSince = async (seq: number) =>
 		(
 			(await (await req(`/v1/validation?sinceSeq=${seq}`)).json()) as {
@@ -156,3 +169,107 @@ test("qos-overrides: tier-2 topicOverrides beats the tier-3 per-service default
 	expect(flagged[0]?.kind).toBe("schema");
 	expect(flagged[0]?.errors?.[0]?.keyword).toBe("enum");
 });
+
+// [itest->R-038]
+test("multi-format (3.1.0): the Multi Format Schema Object payload is enforced through the stack in BOTH directions, never accepted wholesale", async () => {
+	const fx = await bootFixture(4, "multi-format.yaml");
+
+	// false-negative check, toClient: the wrapper's INNER schema is what
+	// validates. Spread verbatim it carries no validation keywords, so this
+	// payload passed green through the whole stack before D-018.
+	const bad = await fx.post("/v1/publish", {
+		topic: "reading/s-1",
+		payload: { sensorId: "s-1", celsius: "hot" },
+	});
+	expect(bad).toMatchObject({
+		direction: "toClient",
+		matched: true,
+		injected: true,
+	}); // delivered
+	const flagged = await fx.violationsSince(bad.sinceSeq);
+	expect(flagged).toHaveLength(1);
+	expect(flagged[0]?.kind).toBe("schema");
+	expect(flagged[0]?.errors?.[0]?.keyword).toBe("type");
+
+	// false-positive check: the clean payload raises nothing
+	const ok = await fx.post("/v1/publish", {
+		topic: "reading/s-1",
+		payload: { sensorId: "s-1", celsius: 21.5 },
+	});
+	expect(await fx.violationsSince(ok.sinceSeq)).toEqual([]);
+
+	// the client-publish path carries the wrapper too: a fromClient channel
+	// (action: receive) rejects an off-contract publish on the same terms
+	const badIn = await fx.post("/v1/publish", {
+		topic: "calibrate/s-1",
+		payload: { offset: "way-off" },
+	});
+	expect(badIn).toMatchObject({
+		direction: "fromClient",
+		matched: true,
+		injected: true,
+	});
+	const flaggedIn = await fx.violationsSince(badIn.sinceSeq);
+	expect(flaggedIn).toHaveLength(1);
+	expect(flaggedIn[0]?.kind).toBe("schema");
+	expect(flaggedIn[0]?.errors?.[0]?.keyword).toBe("type");
+
+	const okIn = await fx.post("/v1/publish", {
+		topic: "calibrate/s-1",
+		payload: { offset: 0.5 },
+	});
+	expect(await fx.violationsSince(okIn.sinceSeq)).toEqual([]);
+});
+
+// [itest->R-037]
+// [itest->R-039]
+test("v2-oldest (2.0.0): the floor of the range loads, its subscribe/publish inversion validates the right way round, and its mqtt binding reaches the wire", async () => {
+	const fx = await bootFixture(5, "v2-oldest.yaml");
+
+	// the 2.x `subscribe` operation binding (qos 2 + retain) reaches the wire,
+	// which nothing upstream validates: 2.x maps `mqtt` to an empty schema
+	const ok = await fx.post("/v1/publish", {
+		topic: "legacy/d-1/telemetry",
+		payload: { deviceId: "d-1", celsius: 21 },
+	});
+	expect(ok.direction).toBe("toClient"); // 2.x `subscribe` = the SERVICE publishes
+	expect(await fx.violationsSince(ok.sinceSeq)).toEqual([]);
+	const entry = (await fx.state()).find(
+		(e) => e.topic === "legacy/d-1/telemetry",
+	);
+	expect(entry?.qos).toBe(2);
+	expect(entry?.retain).toBe(true);
+
+	// false-negative check on the oldest major: an off-type payload is flagged
+	const bad = await fx.post("/v1/publish", {
+		topic: "legacy/d-1/telemetry",
+		payload: { deviceId: "d-1", celsius: "warm" },
+	});
+	expect(bad).toMatchObject({ matched: true, injected: true }); // delivered
+	const flagged = await fx.violationsSince(bad.sinceSeq);
+	expect(flagged).toHaveLength(1);
+	expect(flagged[0]?.kind).toBe("schema");
+	expect(flagged[0]?.errors?.[0]?.keyword).toBe("type");
+
+	// the `publish` operation normalized to fromClient (the inversion the 2.x
+	// spec mandates), and its message schema is enforced on that path too
+	const badIn = await fx.post("/v1/publish", {
+		topic: "legacy/d-1/command",
+		payload: { mode: "broil" },
+	});
+	expect(badIn).toMatchObject({
+		direction: "fromClient",
+		matched: true,
+		injected: true,
+	});
+	const flaggedIn = await fx.violationsSince(badIn.sinceSeq);
+	expect(flaggedIn).toHaveLength(1);
+	expect(flaggedIn[0]?.kind).toBe("schema");
+	expect(flaggedIn[0]?.errors?.[0]?.keyword).toBe("enum");
+
+	const okIn = await fx.post("/v1/publish", {
+		topic: "legacy/d-1/command",
+		payload: { mode: "heat" },
+	});
+	expect(await fx.violationsSince(okIn.sinceSeq)).toEqual([]);
+});
diff --git a/test/spikes/jsf-fidelity.test.ts b/test/spikes/jsf-fidelity.test.ts
index d1f6bdc..5741b23 100644
--- a/test/spikes/jsf-fidelity.test.ts
+++ b/test/spikes/jsf-fidelity.test.ts
@@ -12,9 +12,17 @@ const SEEDS = Array.from({ length: 10 }, (_, i) => i + 1);
 const EXPECTED: Record<string, { draws: number; failures: number }> = {
 	"composition.yaml": { draws: 20, failures: 0 },
 	"external-ref.yaml": { draws: 10, failures: 0 },
+	// re-measured 2026-07-30 when multi-format.yaml joined the fixture set
+	// (D-018): 2 channels x 10 seeds, zero recheck failures, so the D-008
+	// verdict is unchanged on the newest-supported-major fixture too.
+	"multi-format.yaml": { draws: 20, failures: 0 },
 	"qos-overrides.yaml": { draws: 20, failures: 0 },
 	"qos-retain.yaml": { draws: 10, failures: 0 },
 	"thermostat.yaml": { draws: 20, failures: 0 },
+	// re-measured 2026-07-30 when v2-oldest.yaml joined the fixture set (D-018):
+	// 2 channels x 10 seeds, zero recheck failures, so the D-008 verdict holds on
+	// the oldest-supported-major fixture too.
+	"v2-oldest.yaml": { draws: 20, failures: 0 },
 	"v2-pubsub.yaml": { draws: 20, failures: 0 },
 };
 
diff --git a/test/transport-isolation.test.ts b/test/transport-isolation.test.ts
index 99b0b0c..6cbce52 100644
--- a/test/transport-isolation.test.ts
+++ b/test/transport-isolation.test.ts
@@ -16,7 +16,7 @@ function walk(dir: string): string[] {
 }
 
 const TRANSPORT =
-	/from ["'](aedes|aedes-server-factory|mqtt|mqtt-packet|mqtt-connection|ws|websocket-stream)["']|require\(["'](aedes|aedes-server-factory|mqtt|mqtt-packet|mqtt-connection|ws|websocket-stream)["']\)/;
+	/from\s+["'](aedes|aedes-server-factory|mqtt|mqtt-packet|mqtt-connection|ws|websocket-stream)["']|require\(\s*["'](aedes|aedes-server-factory|mqtt|mqtt-packet|mqtt-connection|ws|websocket-stream)["']\s*\)/;
 
 test("only src/broker/ imports a transport package (aedes/mqtt/ws family) — repo-wide", () => {
 	const offenders = walk("src")
diff --git a/test/upstream-drift.test.ts b/test/upstream-drift.test.ts
new file mode 100644
index 0000000..a2461de
--- /dev/null
+++ b/test/upstream-drift.test.ts
@@ -0,0 +1,108 @@
+// R-037 / R-039 — the upstream-drift gate. offbook hand-authors two constants
+// that mirror @asyncapi/specs (the supported version set and the mqtt operation
+// binding's key contract) rather than deriving them at runtime, because a value
+// being present upstream is not the same as offbook having tested it (D-018,
+// D-019). Hand-authored constants go stale silently, so this gate makes the
+// drift loud at the dependency bump, which is the moment someone can act on it.
+// @asyncapi/specs is a devDependency: this file is the ONLY place it may be
+// imported, which the third check enforces.
+// [stest->R-037]
+// [stest->R-039]
+import { expect, test } from "bun:test";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import specs from "@asyncapi/specs";
+import mqttOperationBinding from "@asyncapi/specs/bindings/mqtt/0.2.0/operation.json" with {
+	type: "json",
+};
+import { SUPPORTED_SPEC_VERSIONS } from "#src/model/spec-version.ts";
+import {
+	MQTT_EXTENSION_KEY,
+	MQTT_OPERATION_KEYS,
+} from "#src/registry/index.ts";
+
+function walk(dir: string): string[] {
+	return readdirSync(dir).flatMap((name) => {
+		const p = join(dir, name);
+		return statSync(p).isDirectory() ? walk(p) : [p];
+	});
+}
+
+// `import(...)` alongside `from "…"` / `require(…)`, all with the same
+// whitespace tolerance, so a literal dynamic import
+// (`await import("@asyncapi/specs/…")`) cannot slip past the devDependency
+// guard below. Dynamic import is a live idiom here, which is why the branch
+// earns its place: src/engine/dispatch.ts:70 loads handler modules that way,
+// though it passes a VARIABLE. That form still evades this guard by design,
+// as does `require.resolve(…)`: matching either would need real static
+// analysis, not a source-text regex.
+const ASYNCAPI_SPECS_IMPORT =
+	/from\s+["']@asyncapi\/specs(\/[^"']*)?["']|require\(\s*["']@asyncapi\/specs(\/[^"']*)?["']\s*\)|import\(\s*["']@asyncapi\/specs(\/[^"']*)?["']\s*\)/;
+
+test("SUPPORTED_SPEC_VERSIONS matches the versions @asyncapi/specs exposes", () => {
+	// This test's premise is that the ROOT @asyncapi/specs (our devDependency,
+	// what this file imports) is the SAME copy @asyncapi/parser resolves at
+	// runtime. They are deduped today, but nested copies are a real phenomenon
+	// in this very tree (node_modules/@asyncapi/parser/node_modules/ajv-formats
+	// exists). If a future parser bump ever carries its own nested
+	// @asyncapi/specs, this comparison would silently run against the WRONG
+	// copy at exactly the moment — a version bump — it exists to catch
+	// something. Fail loud instead: if this ever exists, resolve the comparison
+	// through the parser's own dependency instead of the root import above.
+	expect(
+		existsSync("node_modules/@asyncapi/parser/node_modules/@asyncapi/specs"),
+	).toBe(false);
+
+	// Exact equality, no filtering: the 2.0.0-rc1/rc2 AND every 1.x schema exist
+	// on disk but are excluded from the export map, so `schemas` is exactly the
+	// release set offbook cares about.
+	//
+	// Red here means a parser bump changed the available versions. The fix is to
+	// verify the new version against the REAL parser, then either add it to the
+	// constant or record a deliberate exclusion in this gate — NOT to derive the
+	// constant from this check unconditionally: verification can fail. Parser
+	// 3.4.0 shipped the 3.1.0 schema and still died inside its own ruleset
+	// (D-018), which this check alone cannot see.
+	expect([...SUPPORTED_SPEC_VERSIONS] as string[]).toEqual(
+		Object.keys((specs as { schemas: Record<string, unknown> }).schemas),
+	);
+});
+
+test("the mqtt operation binding constants match the official schema", () => {
+	// Versioned schemas are immutable upstream, so comparing against a fixed
+	// path (bindings/mqtt/0.2.0/operation.json below) can never itself detect
+	// drift: that file will never change. Real drift arrives as a NEW binding
+	// version directory, which may add legal keys; until offbook's constant is
+	// updated for it, a spec declaring that version would draw a spurious
+	// binding-unknown-key warning — the crying-wolf failure this diagnostic
+	// exists to avoid. So pin the version SET too, not just the pinned
+	// version's content.
+	expect(
+		[...readdirSync("node_modules/@asyncapi/specs/bindings/mqtt")].sort(),
+	).toEqual(["0.1.0", "0.2.0"]);
+
+	const schema = mqttOperationBinding as {
+		properties: Record<string, unknown>;
+		patternProperties: Record<string, unknown>;
+	};
+	expect([...MQTT_OPERATION_KEYS].sort()).toEqual(
+		Object.keys(schema.properties).sort(),
+	);
+	// transcribed character-for-character, so the source strings compare directly
+	expect(Object.keys(schema.patternProperties)).toEqual([
+		MQTT_EXTENSION_KEY.source,
+	]);
+});
+
+test("@asyncapi/specs stays a devDependency: nothing under src/ imports it", () => {
+	// Biome's noRestrictedImports matches whole module specifiers, so it cannot
+	// express "this package at any subpath", and the realistic regression is a
+	// deep JSON import like the one this gate replaced (D-019). Same idiom as
+	// test/transport-isolation.test.ts and ingestion's G12 guard: match the
+	// `from "…"`, `require("…")`, AND `import("…")` edges, not mentions of the
+	// name in prose comments.
+	const offenders = walk("src")
+		.filter((p) => p.endsWith(".ts"))
+		.filter((p) => ASYNCAPI_SPECS_IMPORT.test(readFileSync(p, "utf8")));
+	expect(offenders).toEqual([]);
+});