# llvm-dsdl User Manual -- complete text

Every page of the manual at https://opencyphal-garage.github.io/llvm-dsdl/, concatenated in navigation order.
Generated by tools/docs/build_llms_index.py; the link index alone is at llms.txt.

The showroom's generated type gallery is not included here. Those two dozen pages carry the
full generated code for every type in eight language/profile variants and are four times the
size of the manual itself, which would make this file expensive to fetch for the many readers
who want the manual. Every one of them is listed with its URL in llms.txt.

==================================================================================================
Source: docs/index.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/
==================================================================================================

# llvm-dsdl User Manual

Compiler tooling for OpenCyphal DSDL, built on MLIR and LLVM.

`llvm-dsdl` ships three user-facing tools:

- `dsdlc` for compile/codegen workflows
- `dsdl-opt` for dialect/pass pipeline work
- `dsdld` for language-server workflows

## Contents

| Section | Read it when | Starts at |
|---|---|---|
| [Get Started](start/install.md) | You have not run the tools yet. Two pages, read in order, ending with generated code on disk. | [Install](start/install.md) · [Quick Start](start/quickstart.md) |
| [Reference](reference/index.md) | You know what you want and need the exact spelling, or the exact guarantee. | [Overview](reference/index.md) |
| [Development](development/contributing.md) | You are changing this repository. | [Contributing](development/contributing.md) · [Testing and CI](development/testing.md) |
| [For Agents](agents/index.md) | You are a coding agent or a documentation indexer. | [Agent Guide](agents/index.md) |

## Canonical Documents

- Project README: [README.md](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/README.md)
- Design details: [DESIGN.md](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/DESIGN.md)
- Contributor workflow: [CONTRIBUTING.md](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/CONTRIBUTING.md)

==================================================================================================
Source: docs/start/install.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/start/install/
==================================================================================================

# Install

Two ways to get `dsdlc`, `dsdl-opt`, and `dsdld` onto a machine: download a release build, or build
from source. Take the release binaries unless you intend to work on the compiler itself — they carry
the LLVM runtime they need, so nothing has to be installed first.

## Option 1: Use release binaries

Download binaries from:

- <https://github.com/OpenCyphal-Garage/llvm-dsdl/releases>

Put `dsdlc`/`dsdl-opt`/`dsdld` on your `PATH`.

## Option 2: Build from source

```bash
git clone https://github.com/OpenCyphal-Garage/llvm-dsdl.git
cd llvm-dsdl
git submodule update --init --recursive
cmake --workflow --preset install-bin-release-ci
```

Installed binaries are typically under:

- `build/matrix/ci/install/bin`

## Prerequisites

- CMake 3.25+
- Ninja
- LLVM + MLIR CMake packages (`LLVMConfig.cmake`, `MLIRConfig.cmake`)
- C++20-capable toolchain

See the full developer prerequisites in [Contributing](../development/contributing.md).

==================================================================================================
Source: docs/start/quickstart.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/start/quickstart/
==================================================================================================

# Quick Start

Compile a DSDL namespace into generated code. Each block below is a complete command; run them
against a root namespace directory of your own, or against the `lanyard` namespace in the
[Showroom](../showroom/index.md) if you do not have one yet.

## Show tool help

```bash
dsdlc --help
dsdlc --version
```

## Generate C from a namespace

```bash
dsdlc --target-language c path/to/root_namespace --outdir out/c
```

## Generate profile-agnostic C++ ABI object code

```bash
dsdlc --target-language obj path/to/root_namespace \
  --obj-abi-language cpp \
  --target-endianness little \
  --jobs 8 \
  --outdir out/obj-cpp
```

## See the output before you write anything

The [Showroom](../showroom/index.md) is a namespace of plausible vendor-specific drone datatypes
generated into every supported language and profile. Build the whole tree with:

```bash
cmake --build <build-dir> --target showroom
```

## Next

- CLI options: [dsdlc](../reference/commands/dsdlc.md)
- Backend behaviour: [Backend Overview](../reference/codegen/backends.md)
- Object backend details: [Object Backend](../reference/codegen/object.md)

==================================================================================================
Source: docs/reference/index.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/
==================================================================================================

# Reference

Everything the tools promise, arranged for lookup rather than for reading through.

| Group | Contents |
|---|---|
| [Commands](commands/dsdlc.md) | Switch names, accepted values, and what each tool does with them. |
| [Code Generation](codegen/backends.md) | What each target language emits, and the ordering contract the emitters hold to. |
| [Language Server](lsp/lint-rules.md) | `dsdld`'s rule catalog, index schema, ranking, logging, and AI surface. |
| [Guarantees](guarantees/parity-matrix.md) | What holds across languages, what happens on malformed input, what is reproducible, and what you can verify about a downloaded artifact. |
| [Showroom](../showroom/index.md) | Real definitions compiled into every language and profile, with their wire layout. |

## Commands

- [`dsdlc`](commands/dsdlc.md) — the compiler and codegen driver
- [`dsdl-opt`](commands/dsdl-opt.md) — dialect and pass-pipeline work
- [`dsdld`](commands/dsdld.md) — the language server

## Code generation

- [Backends](codegen/backends.md) — the target languages and what each produces
- [Object Backend](codegen/object.md) — compiled `.o`/`.a` output, ABI, and endianness
- [Emit Order](codegen/emit-order.md) — the canonical serialize/deserialize step order every backend renders

## Language server

- [Lint Rules](lsp/lint-rules.md) — the rule catalog and suppression schema
- [Index Schema](lsp/index-schema.md) — what the workspace index stores
- [Ranking Model](lsp/ranking-model.md) — how completions and symbol results are ordered
- [Logging](lsp/logging.md) — the structured log channel
- [AI Operation](lsp/ai-operation.md) — modes, policy gates, and configuration
- [AI Data Flow](lsp/ai-data-flow.md) — what enters the AI surface, what leaves it, what is retained

## Guarantees

- [Cross-Language Parity](guarantees/parity-matrix.md) — which backends are covered for which behaviours
- [Malformed Input](guarantees/malformed-input.md) — what each backend does with input it should reject
- [Determinism](guarantees/determinism.md) — what is byte-reproducible, and across which axes
- [Supply Chain](guarantees/supply-chain.md) — the LLVM version lock, SBOM, and what you can verify about a release

### The guarantee pages are generated

`parity-matrix`, `malformed-input`, and `determinism`, along with the [Consistency
Lint](../development/convergence-scorecard.md) under Development, are written by the report
generators under `tools/convergence/` and rebuilt whenever the site is published.

Each page carries a **gating mode** banner.

==================================================================================================
Source: docs/reference/commands/dsdlc.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/commands/dsdlc/
==================================================================================================

# `dsdlc`

`dsdlc` is the primary compiler/codegen driver. Run `dsdlc --help` for languages, target syntax,
and the full option set.

This page covers behaviour that switch descriptions do not carry.

## Support code

Support code is everything a backend emits that is not derived from a definition. It is rendered
from content compiled into `dsdlc`, and `--generate-support` selects when it is written.

| Backend | Support artifacts |
| --- | --- |
| `c` | `dsdl_runtime.h` |
| `cpp` | `dsdl_runtime.h`, `dsdl_runtime.hpp` (per profile) |
| `rust` | `Cargo.toml`, `src/dsdl_runtime.rs`, `src/dsdl_runtime_semantic_wrappers.rs` |
| `go` | `go.mod`, `dsdlruntime/dsdl_runtime.go` |
| `ts` | `package.json`, `dsdl_runtime.ts` |
| `python` | `pyproject.toml`, `_dsdl_runtime.py`, `_runtime_loader.py`, `py.typed` |

Under `never`, Python still writes the `__init__.py` chain its generated modules import through.

## Dependency files

`-MD` writes a make-style `.d` beside each generated output listing the `.dsdl` files it was built
from: its own definition plus the transitive closure of the composite types it references.

Some outputs have no `.dsdl` source to name: definitions from the [embedded `uavcan`
catalog](#embedded-uavcan-catalog) and all [support code](#support-code) are compiled into the
binary. Those rules name **the `dsdlc` executable** as their prerequisite instead — upgrading the
compiler rebuilds what it produced. An output mixing local and embedded definitions lists its real
inputs and the executable.

Every path emitted in a depfile or by `--list-inputs` exists on disk, so both can be fed to a build
system verbatim.

## Pruning stale output

`dsdlc` writes what it is asked for; without `--prune-manifest` it does not remove what it wrote
last time. Delete a definition and its generated header stays in `--outdir`, still on the include
path, so code that names a type nobody defines any more keeps compiling.

`--prune-manifest <file>` closes that. The run records its outputs in `<file>` and, on the next run,
deletes the outputs the previous manifest listed that it no longer produces. Directories emptied
by pruning are removed too, so a deleted namespace leaves no shape behind.

**One manifest per invocation, not per output directory.** Generation
[decomposes](#support-code) — a build may split one namespace across several runs for support, the
embedded catalog, and definitions — and a run owns only the files it emits. A run that swept
`--outdir` would delete the files its siblings had just written, so each tranche is given its own
manifest and prunes only what it owns:

```bash
dsdlc -l c --outdir gen --generate-support only  --prune-manifest .dsdlc/support
dsdlc -l c --outdir gen --generate-support never --prune-manifest .dsdlc/builtin +uavcan.node
dsdlc -l c --outdir gen --generate-support never --omit-dependencies \
      --prune-manifest .dsdlc/types dsdl/myns
```

Removals are confined to `--outdir`: a manifest naming anything outside it is a hard error rather
than a deletion, since a manifest is an input and an input that can name any path is a way to turn a
stale file into an arbitrary `rm`. A manifest in an unrecognised format is treated as absent — a
format change should cost one stale file, not every configured tree.

The flag is ignored under `--dry-run` and the `--list-*` modes, which imply it. A dry run that
deleted files while reporting that it wrote none would be worse than either.

## Embedded uavcan catalog

For the standard `uavcan.*` namespace, `dsdlc` ships an embedded catalog used by the `mlir` and
codegen targets. Types referencing core `uavcan` definitions resolve without external `uavcan`
source roots.

The catalog is consulted automatically during dependency resolution, and can be named directly as a
target with the `+` sigil.

`+` targets behave as explicit targets: their dependency closure is generated too, and
`--omit-dependencies` restricts output to what was named. They mix freely with filesystem targets,
and a local definition sharing a type key shadows the embedded one.

Namespace matching is anchored at a dot boundary, so `+uavcan.n` selects nothing rather than
standing in for `+uavcan.node`. A selector matching nothing is an error with a did-you-mean; an
unavailable version reports the versions the catalog carries.

## Deprecation

A definition marked `@deprecated` generates a `Deprecated: …` notice in its documentation comment and
an `IS_DEPRECATED` metadata constant (`DSDL_IS_DEPRECATED` in TypeScript and Python,
`<TYPE>_IS_DEPRECATED_` in C), in every language. Go recognises the `Deprecated: ` doc paragraph, and
TypeScript is additionally given a `/** @deprecated … */` JSDoc block.

C, C++, and Rust additionally get a language-native attribute — `__attribute__((deprecated))`,
`[[deprecated]]`, and `#[deprecated]` respectively — so naming the type produces a compiler
diagnostic. This is **on by default**.

Each generated file suppresses deprecation diagnostics across its own body (`#pragma GCC diagnostic
ignored "-Wdeprecated-declarations"`, or `#![allow(deprecated)]` in Rust). The suppression is scoped
to the generated file: including generated headers is clean under `-Werror`, and only your own code
naming a deprecated type is diagnosed.

The `obj` backend never emits these attributes.

==================================================================================================
Source: docs/reference/commands/dsdl-opt.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/commands/dsdl-opt/
==================================================================================================

# `dsdl-opt`

`dsdl-opt` is the pass-driver for the `dsdl` MLIR dialect.

Use it to inspect and transform lowered DSDL IR through specific pass pipelines.

## Typical use

```bash
dsdlc --target-language mlir path/to/ns > input.mlir
dsdl-opt input.mlir -pass-pipeline='builtin.module(lower-dsdl-exec,dsdl-annotate-aliasability,dsdl-legalize-endianness)'
```

## Uses

- Debug pass behaviour in isolation
- Validate contract attributes across pipeline boundaries
- Build reproducible IR test cases for lit/unit tests

## Related

- [Architecture](../../development/architecture.md) — the dialect as a contract boundary, and the
  pass sequence these pipelines are built from

==================================================================================================
Source: docs/reference/commands/dsdld.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/commands/dsdld/
==================================================================================================

# `dsdld`

`dsdld` is the DSDL language server (LSP over stdio JSON-RPC).

It is editor/client configured (settings-driven), not primarily CLI-flag driven.

## Run

```bash
dsdld
```

## Typical client settings

- `roots`
- `lookupDirs`
- lint enablement
- AI feature mode and trace settings

## Editor integration

- Neovim: configure via `nvim-lspconfig`

## Related operator docs

- [AI Operation](../lsp/ai-operation.md)
- [Index Schema](../lsp/index-schema.md)
- [Lint Rules](../lsp/lint-rules.md)

==================================================================================================
Source: docs/reference/codegen/backends.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/codegen/backends/
==================================================================================================

# Backend Overview

`dsdlc` shares one frontend/semantic pipeline and dispatches to multiple backend emitters.

## Targets

- `c`: C headers + implementation
- `cpp`: C++ model/runtime outputs (`std`, `pmr`, `autosar`)
- `rust`: crate/module output with profile/runtime controls
- `go`: module/package output
- `ts`: typed model + runtime helpers
- `python`: package + runtime loader/specialization
- `obj`: compiled `.o` + optional `.a`

## Shared principles

- One semantic interpretation per DSDL source set
- Contract-validated lowering boundaries
- Deterministic file planning
- Backend parity coverage in CI

## Object code path

The `obj` lane runs executable lowering and emits compiled artifacts via host compiler toolchains.

See [Object Backend](object.md) for endianness, ABI, and artifact details.

==================================================================================================
Source: docs/reference/codegen/object.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/codegen/object/
==================================================================================================

# Object Backend (`-l obj`)

The object backend compiles generated sources into static objects and optional archives.

## ABI lanes

## C lane (`--obj-abi-language c`)

- Stages generated C under `.obj_stage_c`
- Compiles C translation units to `.o`
- Optionally archives into `.a`
- Publishes the staged headers into `--outdir`

## Headers

The staged sources are an intermediate this backend compiles itself, but the headers are the only way
to call what ends up in the archive, so they are copied into `--outdir` and reported by
`--list-outputs` like any other output. The layout matches what the `c` backend produces, so
`-I<outdir>` plus the archive is a complete interface from a single invocation.

The staging directories remain, and remain private: nothing should read `.obj_stage_c` or
`.obj_stage_cpp`, and their contents are not declared outputs.

## C++ lane (`--obj-abi-language cpp`)

- Uses canonical profile-agnostic C++ ABI types
- Exports C++ ABI symbols plus C-callable shim symbols
- Stages under `.obj_stage_cpp` (including nested C stage)

## Endianness semantics

The DSDL wire format is little-endian on every target, so `serialize_`/`deserialize_`
perform explicit little-endian bit assembly and are independent of host endianness.
`--target-endianness` selects the codegen/legalization strategy; it does not change
wire-contract semantics. There is no byte-swap step.

- `little`: all fast paths are available, including the zero-copy view helpers
  (`try_deserialize_view_` / `try_serialize_view_`) for alias-eligible fixed-size
  sealed layouts.
- `big`: `serialize_` / `deserialize_` are fully supported and produce byte-identical
  wire output to `little` (verified by the object-backend smoke test). The zero-copy
  view helpers are disabled and return `-DSDL_RUNTIME_ERROR_INVALID_ARGUMENT`.

**Note:** the big-endian path is validated by compiling the
`LLVMDSDL_TARGET_ENDIANNESS_BIG` code path and asserting wire byte-parity on a
little-endian host; it is not yet exercised on real big-endian hardware in CI.

## Example

```bash
dsdlc --target-language obj path/to/ns \
  --obj-abi-language cpp \
  --target-endianness little \
  --obj-archive-name my_dsdl \
  --jobs 12 \
  --outdir out/obj
```

==================================================================================================
Source: docs/reference/codegen/emit-order.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/codegen/emit-order/
==================================================================================================

# Canonical emit order

The reference **abstract** serialize/deserialize step order that every string backend
(Rust, Go, C++, TypeScript, Python) follows. This is a live contract, not a historical
plan: the shared render template produces this order by construction, and the emit-order
verifier (`tools/convergence/emit_order_verifier.py`, ctest `llvmdsdl-emit-order-verifier`)
independently pins it on every build.

This prose is the human-readable projection of the machine-checked model in
[spec/dafny/CyphalSerdes.dfy](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/spec/dafny/CyphalSerdes.dfy), which *proves* (unbounded,
by induction) that serialize/deserialize round-trip and that the read path is bounds-safe, and
defines the accepted op orderings (`SerOrderOK`/`DeOrderOK`). The model is the source of truth;
this doc is the readable shadow.

**Where the order lives in code.** `buildUnionSectionSteps` and `buildFieldEmitSteps`
([`include/llvmdsdl/CodeGen/EmitStep.h`](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/include/llvmdsdl/CodeGen/EmitStep.h)) build the step list/tree;
`renderUnionSection` and `renderFieldSteps`
([`lib/CodeGen/EmitStepRender.cpp`](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/lib/CodeGen/EmitStepRender.cpp)) own every
cross-statement ordering decision, recursively. Per-backend `UnionSectionSpelling` /
`FieldStepSpelling` classes contain *zero sequencing* — only leaf statement idioms. A
backend cannot reorder these steps; it can only exercise a declared right
(see [Accepted differences](#accepted-differences)).

## Abstract order vs spelling

The emit-order verifier checks **abstract op order**, not surface text. Two backends agree if they perform the same
ordered sequence of abstract ops, regardless of how each op is spelled.

- **Abstract op** (the emit-order verifier asserts these, cross-backend identical): `VALIDATE_TAG`, `MASK_TAG`,
  `WRITE_TAG`, `ADVANCE`, `SWITCH`, `CASE`, `ALIGN`, `WRITE_SCALAR`, … (full list below).
- **Spelling** (the shared-render-template visitor varies these; the emit-order verifier is deliberately blind to them): whether a
  mask is a separate statement or an inline sub-expression; `match` vs `switch` vs `if/elif`;
  `Result`/`Err` vs `(rc,0)` vs negative-int return vs `throw`/`raise`; identifier names;
  indentation.

Example: in `serialize` of a union tag, Rust/Go write `set_uxx(buf, off, mask(tag), bits)`
(mask folded into the write argument) while TS emits `tag = mask(tag);` then
`writeUnsigned(...tag...)` (mask as its own statement). **Both are `VALIDATE_TAG → MASK_TAG →
WRITE_TAG`** — identical abstract order, different spelling. The emit-order verifier treats them as equal. This
case doubles as a verifier insensitivity check (D1 below).

## Two invariant principles

1. **Write path validates before it emits; read path reads before it validates.** On
   serialize, a value is range/tag/length-validated *before* the corresponding `WRITE_*`. On
   deserialize, the raw bits are `READ_*` first, then masked/validated. This asymmetry is
   intentional and appears identically for the union tag and the array length prefix.
2. **`ADVANCE` (`offset_bits += N`) happens immediately after the matching `WRITE_*`/`READ_*`,
   never before.** Alignment padding (`ALIGN`) is emitted *before* a field's value ops.

## Section level

### Struct (non-union) — serialize and deserialize
For each lowered field step, in lowered order:
```
(padding step)  → ALIGN(pad.bits) → PAD(write/skip zero bits) → ADVANCE
(value step)    → ALIGN(field.alignmentBits) → <field ops, see Field level>
end of section  → ALIGN(8)          # trailing pad to byte boundary
```

### Union — serialize
```
VALIDATE_TAG          # unionTagValidate(tag); error-branch on failure
MASK_TAG              # unionTagMask(tag)
WRITE_TAG(tagBits)    # set_uxx / writeUnsigned
ADVANCE(tagBits)
SWITCH(tag) {
  CASE(optionIndex):
    ALIGN(option.alignmentBits)
    <option field ops, see Field level>
  ...
  DEFAULT: DEFAULT_BAD_TAG          # -REPRESENTATION_BAD_UNION_TAG
}
```

### Union — deserialize
```
READ_TAG(tagBits)     # get_u64 / readUnsigned
MASK_TAG              # unionTagMask(raw)
STORE_TAG             # obj.tag = masked
VALIDATE_TAG          # unionTagValidate(tag); error-branch
ADVANCE(tagBits)
SWITCH(tag) { CASE(optionIndex): ALIGN(...) <field ops> ... DEFAULT: DEFAULT_BAD_TAG }
```
Note `READ → MASK → STORE → VALIDATE` on deserialize vs `VALIDATE → MASK → WRITE` on serialize
(principle 1). All five backends emit this by construction via `renderUnionSection`.

## Field level

`emitSerializeAny` / `emitDeserializeAny` dispatch on cardinality: array → [Array], else
scalar/composite → [Scalar]/[Composite].

### Scalar — serialize (by `SemanticScalarCategory`)
```
Bool:                       WRITE_SCALAR(set_bit, 1)             → ADVANCE(1)
Unsigned/Byte/Utf8:  CAST(u64) → HELPER(mask|saturate) → WRITE_SCALAR(set_uxx, bits) → ADVANCE(bits)
Signed:              CAST(i64) → HELPER(mask|saturate) → WRITE_SCALAR(set_ixx, bits) → ADVANCE(bits)
Float:               CAST(fN)  → HELPER(width-matched)  → WRITE_SCALAR(set_f16|f32|f64) → ADVANCE(bits)
Void:                → [Padding]
Composite:           → [Composite]
```
The saturating/masking `HELPER` is applied to the value **before** `WRITE_SCALAR` (principle 1).
Float helpers are width-matched (f32 for 16/32-bit, f64 for 64-bit) so no native backend
canonicalizes signaling-NaN payloads through a `float→double→float` round-trip.

### Scalar — deserialize
```
Bool:                       READ_SCALAR(get_bit)                → ADVANCE(1)
Unsigned/Byte/Utf8:  READ_SCALAR(get_uN) → HELPER(mask) → CAST(store) → ADVANCE(bits)
Signed:              READ_SCALAR(get_u64) → HELPER → CAST(signed store) → ADVANCE(bits)
Float:               READ_SCALAR(get_fN) → HELPER → CAST(store) → ADVANCE(bits)
```

### Array — serialize
```
Fixed:     LEN_CHECK(len == capacity)          # exact-length guard
Variable:  LEN_VALIDATE(len) → MASK(prefix) → LEN_WRITE(prefixBits) → ADVANCE(prefixBits)
ELEM_LOOP(0..count) { <element scalar/composite ops> }     # count = len (var) or capacity (fixed)
```

### Array — deserialize
```
Variable:  LEN_READ(prefixBits) → ADVANCE(prefixBits) → MASK(prefix) → STORE(count) → LEN_VALIDATE(count)
Fixed:     count = capacity
CLEAR → RESERVE(count) → ELEM_LOOP(0..count) { DEFAULT_ELEM → <element deserialize ops> → PUSH }
```
Same validate asymmetry: serialize `LEN_VALIDATE` before `LEN_WRITE`; deserialize `LEN_READ`
before `LEN_VALIDATE`.

Array steps own their element's step subtree, so nesting is decided once in shared code and
`renderFieldSteps` recurses into the element for both directions.

### Composite
```
Sealed:     COMPOSITE_INLINE           # inline nested serialize/deserialize at current offset
Delimited:  COMPOSITE_DELIM_HEADER(32) # 32-bit delimiter/extent header, then nested payload
```

**Sealed** — no header. The nested call runs against the buffer from the current byte offset;
the cursor advances by the bytes the nested call reports consuming (`ADVANCE(consumed * 8)`).

**Delimited — serialize** (length backpatch):
```
ADVANCE(32)                             # reserve the header slot; write it last
size = ceil(bitLengthSet.max() / 8)     # worst-case bound for the sub-buffer
VALIDATE(size <= remaining capacity)    # delimiterValidateSymbol helper; error-branch
nested serialize into buffer[start .. start+size]   # returns the ACTUAL byte count
size = <actual returned count>
WRITE header(32) at (offset_bits - 32) = size       # the backpatch
ADVANCE(size * 8)
```

**Delimited — deserialize** (bounded read):
```
READ header(32) → size
ADVANCE(32)
VALIDATE(size <= remaining capacity)    # same helper; error-branch
nested deserialize from buffer[start .. start+size]  # bounded to exactly `size` bytes
ADVANCE(size * 8)                       # by the HEADER size, never by nested-consumed
```
That last line is the forward-compatibility rule and is load-bearing: advancing by the
nested call's consumed count instead of the header value silently corrupts version-skew
decoding, because a newer sender's extra trailing bytes must be *skipped*, not re-read as
the next field. The trace records one `COMPOSITE_DELIM_HEADER` op; the mechanics above are
spelled per backend inside `spellCompositeSerialize` / `spellCompositeDeserialize`.

### Padding / void
```
ALIGN(pad.bits) → PAD(write/skip zeroed bits) → ADVANCE(pad.bits)
```

## Abstract op vocabulary

Mirrored by `enum class EmitTraceOp` in
[`include/llvmdsdl/CodeGen/EmitTrace.h`](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/include/llvmdsdl/CodeGen/EmitTrace.h) — this doc and
that enum are kept in step.

`VALIDATE_TAG` · `MASK_TAG` · `WRITE_TAG` · `READ_TAG` · `STORE_TAG` · `SWITCH` · `CASE` ·
`DEFAULT_BAD_TAG` · `ALIGN` · `WRITE_SCALAR{bool|uint|sint|float}` ·
`READ_SCALAR{bool|uint|sint|float}` · `LEN_CHECK` · `LEN_VALIDATE` · `LEN_WRITE` · `LEN_READ` ·
`ELEM_LOOP` · `BULK_COPY` · `COMPOSITE_INLINE` · `COMPOSITE_DELIM_HEADER` · `PAD` · `ADVANCE`.

Each op carries a small payload where relevant (bit width, option index, scalar sub-kind). The emit-order verifier
normalizes away identifiers and indentation, keeping op + payload — payloads are compared,
so a wrong bit width or option index fails even when op names agree.

Two structural elements beyond the wire ops: `BULK_COPY` (payload = total bits) is the honest trace
of the C++ fixed-bool-array fast path — the D3 declared equivalence
`BULK_COPY ≡ ELEM_LOOP + 1-bit bool scalar` is applied by the comparator, never silently.
`SECTION <canonical.name> <serialize|deserialize>` header events segment the trace per
(type, direction) so divergences localize and cannot cancel across type boundaries.

**Trace calls live at the spelling sites, not in the shared render template.** This is
deliberate: tracing the shared sequencer would be tautological for order. Because each
backend traces the tokens it actually emits, the verifier stays an independent check on the
shared template rather than a restatement of it.

## Accepted differences

Cross-backend differences fall into three classes: invisible by design (spelling), a declared
right exercised through a named interface point, or genuine abstract-order divergence. Only
the third is a defect. All are explicitly modeled — never silently ignored. This is exactly
the class of structural fact the marker-regex "convergence" score cannot see.

| # | Backend(s) | Kind | Resolution |
|---|---|---|---|
| D1 | TS/Python mask the union tag as its own statement; Rust/Go fold it into the write argument | **Spelling only** — abstract order `VALIDATE→MASK→WRITE` is identical | Both kept. Serves as the verifier's insensitivity case: it must report *equal* |
| D2 | Fixed-array `LEN_CHECK`: **Rust emits it** (Vec/slice, runtime `len != capacity` guard); **Go/C++ do not** (fixed arrays are compile-time-sized `[N]T` / `std::array`, so the guard is subsumed by the type system — no emit site) | **Structural, accepted** — type-system-subsumed, not missing | Declared interface point `FieldStepSpelling::spellFixedArrayLenCheck` (a documented no-op in Go/C++); `LEN_CHECK` is backend-optional in the comparator skeleton |
| D3 | C++ has a **bulk-copy fast path for fixed `bool` arrays** (`dsdl_runtime_copy_bits`/`get_bits`) that returns before the element loop, so it emits no `ELEM_LOOP` / per-element scalar ops for that case | **Genuine C++ optimization** | Declared interface point `FieldStepSpelling::trySpellArrayBulkFastPath`; traces an honest `BULK_COPY`, and the comparator applies the declared equivalence `BULK_COPY ≡ ELEM_LOOP + 1-bit bool scalar` (selftest-pinned, exercised by the `BoolArray` fixture) |
| D4 | **TS/Python union deserialize** once emitted `READ_TAG → ADVANCE → MASK_TAG → VALIDATE_TAG → STORE_TAG` against the canonical `READ → MASK → STORE → VALIDATE → ADVANCE` | **Was a genuine order difference, safe** — read-before-mask-before-validate all held; only `STORE`/`ADVANCE` bookkeeping positions differed | **Closed by construction**: all five backends render the union prologue through `renderUnionSection`, so the raw prologue traces are identical. The comparator's bookkeeping tolerance is retained for robustness but is no longer exercised by unions |
| D5 | *(further genuine reorderings)* | **None.** All 5 backends verified over unions, variable/fixed arrays, floats, signed+void padding, fixed bool arrays, sealed + delimited composites, arrays of composites, and a service type (26 fixture segments), plus the full UAVCAN public-regulated corpus (424 segments) | Zero unmodeled divergences |

## Enforcement

Three ctests (labels `integration;convergence;emit-order`) run in every ctest-driven CI lane:

| Test | What it proves |
|---|---|
| `llvmdsdl-emit-order-verifier` | Every backend's trace is a member of the Dafny-proven safe ordering class, and the payload-aware wire skeletons agree cross-backend — over the fixtures and, when the submodule is present, the full UAVCAN corpus |
| `llvmdsdl-emit-order-verifier-selftest` | The checker itself has teeth: mask-before-validate rejected, payload divergence detected, D3 equivalence honored, `BULK_COPY` without `ADVANCE` rejected |
| `llvmdsdl-emit-order-verifier-mutation` | The whole pipeline has teeth: dsdlc re-runs with `LLVMDSDL_EMIT_TRACE_MUTATE=swap-tag-validate` and the verifier must go red |

**Scope**: the 5 string emitters. **C is out of scope** — it lowers through MLIR
`convert-dsdl-to-emitc` with no string emitter, and is covered instead by the
C↔{Go,Rust,Cpp} parity harnesses. State coverage as "5 string emitters + C via parity",
never "six". Driving EmitC from the step IR is a separate, unscoped epic.

## History

This document began as the Phase 0 oracle for the P2 emit-order deduplication work, which
sequenced the emit-order verifier before the shared render template and completed on
2026-07-12. That work is closed and its execution plan has been retired; this document
outlives it as the standing specification. The plan's own record of how it landed —
per-phase status, the byte-identity proofs, the LOC-delta accounting — is preserved in the
G1 section of [the project report](../../development/roadmap.md) and in git
history (`docs/plans/P2_emit_order_dedup.md`, removed 2026-07-31).

==================================================================================================
Source: docs/reference/lsp/lint-rules.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/lint-rules/
==================================================================================================

# LSP Lint Rules

## Overview

The `dsdld` lint engine runs deterministic rule checks over parsed DSDL ASTs and
emits diagnostics with optional autofix edits.

Rule IDs are stable and can be suppressed via configuration or source comments.

For rule implementation workflow, see `docs/development/lint-rule-authoring.md`.

## Baseline Rules (v1)

1. `naming.type_pascal_case`
2. `naming.field_snake_case` (autofix)
3. `naming.constant_upper_snake_case` (autofix)
4. `naming.namespace_lowercase`
5. `style.no_tabs` (autofix)
6. `style.trailing_whitespace` (autofix)
7. `style.single_trailing_newline` (autofix)
8. `complexity.max_fields_per_type`
9. `complexity.max_constants_per_type`
10. `complexity.max_directives_per_type`
11. `arrays.large_fixed_bound`
12. `arrays.large_variable_bound`

## Configuration Schema

`workspace/didChangeConfiguration` accepts:

```json
{
  "settings": {
    "lint": {
      "enabled": true,
      "disabledRules": ["arrays.large_fixed_bound"],
      "fileSuppressions": {
        "file:///abs/path/demo/TypeA.1.0.dsdl": ["style.no_tabs"],
        "/abs/path/demo/TypeB.1.0.dsdl": ["*"]
      },
      "pluginLibraries": ["/abs/path/libcustom_lints.dylib"]
    }
  }
}
```

## Suppression Model

1. Workspace-level suppression: `lint.disabledRules`
2. Per-file suppression: `lint.fileSuppressions[uri-or-path]`
3. In-source suppression comment:

```text
# dsdld-lint-disable: rule.id.one, rule.id.two
```

Use `*` to suppress all lint rules in a scope.

## Code Actions and Autofix

Lint findings with fixes are exposed as `quickfix` code actions.
Fixes are explicit LSP workspace edits.

## Plugin Extension Path

Shared libraries can provide additional rules by exporting:

```cpp
extern "C" void llvmdsdlRegisterLintRules(llvmdsdl::lsp::LintRegistry& registry);
```

Each plugin registers one or more `LintRuleFactory` instances.

==================================================================================================
Source: docs/reference/lsp/index-schema.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/index-schema/
==================================================================================================

# LSP Index Schema

## Purpose

`dsdld` persists per-file index shards for warm-start workspace indexing and
`workspace/symbol` queries.

Schema version: `1` (`LspIndexSchemaVersion`).

## File Naming

Each source file maps to one shard file in the configured index cache directory.
The source path is encoded into a filesystem-safe key and written as:

- `<encoded-source-path>.index.json`

## JSON Structure

Each shard is a JSON object:

```json
{
  "schema_version": 1,
  "metadata": {
    "file_path": "/abs/path/TypeA.1.0.dsdl",
    "source_uri": "file:///abs/path/TypeA.1.0.dsdl",
    "text_hash": 123456789,
    "snapshot_version": 42
  },
  "symbols": [
    {
      "usr": "type:demo.TypeA.1.0",
      "name": "TypeA",
      "qualified_name": "demo.TypeA.1.0",
      "container_name": "demo",
      "detail": "message",
      "kind": 23,
      "file_path": "/abs/path/TypeA.1.0.dsdl",
      "location": {
        "uri": "file:///abs/path/TypeA.1.0.dsdl",
        "line": 0,
        "character": 0,
        "length": 5
      }
    }
  ],
  "references": [
    {
      "target_usr": "type:demo.TypeA.1.0",
      "file_path": "/abs/path/TypeA.1.0.dsdl",
      "is_declaration": true,
      "location": {
        "uri": "file:///abs/path/TypeA.1.0.dsdl",
        "line": 0,
        "character": 0,
        "length": 5
      }
    }
  ]
}
```

## Schema Guarantees

1. `schema_version` is required and must match the runtime schema constant.
2. Serialization is deterministic for identical shard content.
3. Symbol/reference rows are sorted before persistence.
4. Duplicate logical shards (same `metadata.file_path`) are considered invalid.
5. Invalid shards are reported by verification and can be removed by repair.

## Compatibility Strategy

1. Any schema change increments `schema_version`.
2. Older schema versions are rejected by the current runtime.
3. Unsupported shard files are treated as invalid cache entries.
4. Verification/repair can remove unsupported shards for clean warm-starts.

==================================================================================================
Source: docs/reference/lsp/ranking-model.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/ranking-model/
==================================================================================================

# LSP Ranking Model

How `dsdld` orders the results it returns — which completion comes first, which symbol match wins —
and which signals feed that ordering.

## Scope

This model is used by `dsdld` for:

1. `textDocument/completion` reranking
2. `workspace/symbol` reranking

It is implemented in:

- `include/llvmdsdl/LSP/Ranking.h`
- `lib/LSP/Ranking.cpp`

## Feature Set

Each candidate gets an explainable score breakdown:

1. `lexical_base`: retrieval-stage lexical score
2. `match_quality`: exact/prefix/contains boosts
3. `fuzzy_boost`: subsequence-match boost
4. `frequency_boost`: exposure/selection usage boost
5. `recency_boost`: exponential-decay recency boost
6. `kind_boost`: candidate-kind bias
7. `length_penalty`: small name-length penalty

Final score:

`total_score = lexical_base + match_quality + fuzzy_boost + frequency_boost + recency_boost + kind_boost + length_penalty`

## Adaptive Signals

Signals are tracked per ranking key:

- exposure count
- selection count
- last update tick

Persistence:

- JSON file in index cache directory: `ranking-signals.json`
- bounded size (default max entries: 4096)
- least-recent entries are pruned when full

## Explainability Endpoint

`dsdld/debug/scoreExplain`

Params:

- `kind`: `completion` or `workspaceSymbol`
- `query`: optional query text
- `limit`: optional row count
- for `completion`: `uri`, `line`, `character`

Returns a row list containing candidate identity + full score breakdown.

==================================================================================================
Source: docs/reference/lsp/logging.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/logging/
==================================================================================================

# dsdld structured logging

`dsdld` emits structured, level-gated records so an operator can reconstruct what the server was doing
after the fact — "which request was in flight when the editor stopped responding?"

## Destination

**stderr, one JSON object per line.** stdout carries the JSON-RPC frames and is never interleaved with
log text; the logger serialises writes, so lines stay intact even though records originate from both the
main thread and the request-scheduler worker.

Capture them the way you capture any stderr:

```console
$ dsdld 2> dsdld.log
```

Most editors surface a language server's stderr in an output/log panel.

## Verbosity

Controlled by the standard LSP trace value — there is no bespoke knob:

| Trace | Emits |
| --- | --- |
| `off` | nothing |
| `messages` (default) | `error` / `warn` / `info` — the request-level backbone |
| `verbose` | the above plus `debug` (configuration changes and other high-volume detail) |

Set it three ways, each taking effect immediately:

- `initialize` params: `{"trace": "verbose"}` — applied before the handshake is answered, so the
  handshake itself is logged at the requested level.
- The `$/setTrace` notification: `{"value": "off"}` — the protocol's own runtime control.
- The `trace` workspace setting via `workspace/didChangeConfiguration`.

## Record shape

Every record carries `event` and `level`; the rest is event-specific.

```json
{"event":"request","latency_us":196,"level":"info","method":"initialize","outcome":"ok"}
{"event":"request","latency_us":91240,"level":"info","method":"textDocument/completion","outcome":"cancelled"}
{"code":-32601,"event":"error_response","level":"warn","message":"method not found: nope/bogus"}
{"event":"set_trace","level":"info","value":"verbose"}
{"applied":true,"event":"configuration_changed","level":"debug"}
```

| Event | Level | Meaning |
| --- | --- | --- |
| `request` | info | One record per request — **synchronous and scheduler-completed alike**, because every request funnels through a single telemetry choke point. Carries `method`, `latency_us`, and `outcome` (`ok` or `cancelled`). |
| `error_response` | warn | A request was answered with a JSON-RPC error. Cancellations are routine flow control and stay at `info`. |
| `set_trace` | info | Verbosity changed at runtime. |
| `configuration_changed` | debug | `workspace/didChangeConfiguration` was applied. |

## Deliberate omissions

Records carry **no document text and no secrets** — method names, latencies, and error codes only. The
AI surface's separate audit log applies its own redaction (see `ai-operation.md`); this channel
avoids the problem by never carrying payloads in the first place.

Omitting the log sink entirely (the library default when embedding `lsp::Server`) makes the server
silent regardless of trace level, and the gate short-circuits before any JSON is built, so `off` costs
next to nothing.

==================================================================================================
Source: docs/reference/lsp/ai-operation.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/ai-operation/
==================================================================================================

# LSP AI Operator Guide

This guide describes how to operate AI-assisted features in `dsdld` safely.

## 1. Scope

AI support in `dsdld` is optional and policy-gated.
The default provider is deterministic and offline (`OfflineAiProvider`).

For **what data enters the AI surface, what leaves it, and what is retained** — including the bounds on
how much source can reach the provider and why nothing is transmitted off the machine — see
[`ai-data-flow.md`](ai-data-flow.md).

Relevant code:

1. `include/llvmdsdl/LSP/AI.h`
2. `lib/LSP/AI.cpp`
3. `include/llvmdsdl/LSP/ServerConfig.h`
4. `lib/LSP/Server.cpp`

## 2. AI Modes

Supported modes:

1. `off`: AI disabled.
2. `suggest`: non-edit suggestions and explanations.
3. `assist`: richer suggestions and optional confirmation-required edit proposals.
4. `apply_with_confirmation`: allows edit materialization only with explicit confirmation.

Recommended default for shared repos:

1. `off` for conservative posture.
2. `suggest` for low-risk advisory usage.

## 3. Safety Controls

Implemented controls:

1. Mode gate (`AiPolicyGate`) determines allowed behaviours.
2. Confirmed edits only in `apply_with_confirmation`.
3. Tool-use allow-list blocks unapproved operations.
4. Context packing is bounded in size.
5. Audit records are redacted before storage.

Allowed tool-use names today:

1. `analysis.stats`
2. `workspace.symbols`
3. `document.symbols`
4. `document.diagnostics`

## 4. Configuration

Via `workspace/didChangeConfiguration`:

```json
{
  "settings": {
    "ai": {
      "mode": "suggest"
    }
  }
}
```

VS Code equivalents:

1. `dsdld.aiMode`

## 5. Operational Playbooks

### 5.1 Conservative default

1. Set `aiMode` to `off` or `suggest`.
2. Keep lint enabled for deterministic static checks.
3. Review all code actions before applying.

### 5.2 Controlled edit application

1. Set `aiMode` to `apply_with_confirmation`.
2. Require explicit user confirmation for each AI edit resolution.
3. Keep normal PR/code-review gates unchanged.

### 5.3 Incident response

If suspicious AI behaviour is observed:

1. Set `aiMode` to `off` immediately.
2. Capture `dsdld/debug/aiAuditLog` output.
3. Reproduce with minimal fixture and add a unit test.
4. File fix and document behaviour change.

## 6. Auditing

Audit retrieval endpoint:

1. `dsdld/debug/aiAuditLog`

Redaction currently masks common secret patterns including:

1. `password`
2. `token`
3. `secret`
4. `api_key` / `api-key`
5. `Bearer <token>`

Audit logs are bounded in memory (`MaxRecords`).

## 7. Current Limitations

1. Provider is offline/deterministic and does not call external model APIs yet.
2. No persistent on-disk audit sink is implemented yet.
3. Tool-use surface is intentionally narrow.

## 8. Release Gate Expectations

Before release, verify:

1. Mode gating tests pass.
2. Confirmation gate behaviour passes.
3. Tool allow-list rejects unsupported tools.
4. Redaction tests pass.
5. `docs/reference/lsp/ai-operation.md` matches current behaviour.

==================================================================================================
Source: docs/reference/lsp/ai-data-flow.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/lsp/ai-data-flow/
==================================================================================================

# LSP AI surface: data flow

What data enters the `dsdld` AI surface, what happens to it, what leaves, and what is retained. This is
the *data-flow* companion to `ai-operation.md` (which covers modes, configuration, and
playbooks); read this one to answer "does my DSDL source leave my machine?".

Every claim below names the governing constant or call site.

## Summary

**Nothing leaves the process.** The only implementation of the `AiProvider` interface is
`OfflineAiProvider` (`lib/LSP/AI.cpp`), which runs in-process and computes suggestions locally; the
server hard-wires it at construction (`Server.cpp`, `aiProvider_ = std::make_unique<OfflineAiProvider>()`).
There is no network code anywhere in the AI surface — no HTTP client, no socket, no outbound
request of any kind. Document content reaches a bounded, in-memory packer and a local provider, and
suggestions return to the editor over the same JSON-RPC connection the editor opened.

**And by default nothing runs at all:** `ServerConfig::aiMode` defaults to `AiMode::Off`, and
`AiPolicyGate::isEnabled` is false for `Off`, so the surface is inert until an operator turns it on.

## Entry points

Only four LSP methods reach the AI surface, each behind a policy gate:

| Method | Gate | Reaches |
| --- | --- | --- |
| `textDocument/codeAction` | `AiPolicyGate::canSuggest` | `appendAiCodeActions` → packer → provider |
| `codeAction/resolve` | `canSuggest` | suggestion resolution |
| `dsdld/ai/resolveEdit` | `canApplyConfirmedEdits` — **only** `ApplyWithConfirmation` | edit materialization |
| `dsdld/ai/toolUse` | `isEnabled` **and** `isToolAllowed` | read-only introspection tools |

Nothing else in the server consults `aiProvider_`.

## Inputs and bounds

On a code-action request the server reads the document from its **in-memory overlay**
(`documents_.lookup(uri)` — the editor's live buffer, not the file on disk) and hands it to
`AiContextPacker::buildCodeActionContext`, which packs a deliberately bounded `AiCodeActionContext`:

| Field | Content | Bound (`lib/LSP/AI.cpp`) |
| --- | --- | --- |
| `selectionSnippet` | **Actual document text** around the selection — the only raw source that enters | `MaxSnippetBytes = 640` (truncated) |
| `diagnostics` | Diagnostic *messages* for the range | `MaxDiagnosticMessages = 8` |
| `symbolHints` | Symbol names from `analysis_.documentSymbols(uri)` | `MaxSymbolHints = 24` |
| `uri`, selection range | File URI and start/end line·character | — |
| `documentFacts` | Structural only: `lastLine`, `lastLineLength`, `endsWithNewline`, `hasSealedDirective` | — |

So the maximum document content that can reach the provider on any single request is **640 bytes of
source**, plus symbol names and diagnostic text. The full buffer is read to *locate* the selection, but
is not forwarded.

## Outputs and their effects

The provider returns `AiCodeActionSuggestion` values (`id`, `title`, `kind`, `explanation`,
`diagnosticMessage`, `hasEdit`, `requiresConfirmation`). These become code actions in the editor.

A suggestion **cannot silently modify your files**. `requiresConfirmation` defaults to `true`, and edit
materialization is gated by `AiPolicyGate::canApplyConfirmedEdits`, which is true for exactly one mode —
`ApplyWithConfirmation`. In `Suggest` and `Assist`, edits can be described but never materialized.

### Tool surface

`dsdld/ai/toolUse` is restricted to a four-entry allow-list (`AiPolicyGate::isToolAllowed`):
`analysis.stats`, `workspace.symbols`, `document.symbols`, `document.diagnostics`. All four are
**read-only introspection** of state the server already computed. There is no file-write, no shell, and
no network tool.

## Retention

`AiAuditLogger` keeps records of policy/tool events **in memory only** — there is no filesystem or
network persistence in the AI surface, so the log is lost on restart and never lands on disk. It is
doubly bounded (`include/llvmdsdl/LSP/AI.h`):

- `MaxRecords = 256` — a ring; older records are dropped.
- `MaxDetailBytes = 4096` — per-record detail cap, applied **after** redaction.

Together these bound audit memory at roughly 1 MiB regardless of request size.

### Redaction

`AiAuditLogger::redactSensitive` masks common secret shapes before a record is stored
(case-insensitive):

- JSON members: `"password" | "token" | "secret" | "api_key" | "api-key" : "…"`
- Bare assignments: `password|token|secret|api[_-]?key` followed by `:` or `=`
- `Bearer <token>`

This is pattern-based masking of *known* shapes, not a proof of absence — a secret in an unrecognised
form embedded in DSDL source could still reach an audit record. Treat the audit log as sensitive.

Redaction runs **before** the 4096-byte cap, so truncation cannot leave half a secret unmasked.

## Summary for an operator

- **Default:** off. Nothing is read, computed, or retained.
- **Enabled:** at most 640 bytes of source per request reaches a **local, in-process** provider. Nothing
  is transmitted anywhere.
- **Edits:** never applied without `ApplyWithConfirmation` plus explicit confirmation.
- **Tools:** four read-only introspection calls, closed allow-list.
- **Retention:** in-memory, redacted, ~1 MiB bounded, gone on restart.

See `ai-operation.md` for turning modes on, configuration keys, and incident-response
playbooks, and `logging.md` for the server's separate structured log (which carries no payloads at
all).

==================================================================================================
Source: docs/reference/guarantees/parity-matrix.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/guarantees/parity-matrix/
==================================================================================================

# Parity Matrix Coverage

Which serialization behaviours are covered by tests in every target language, and which are not. A cell is a (backend, behaviour) pair.

Generated by `tools/convergence/parity_matrix_report.py`.

## Summary

| Backend | Score | Covered / Total |
| --- | ---: | ---: |
| `c` | `100` | `8 / 8` |
| `cpp` | `100` | `8 / 8` |
| `go` | `100` | `8 / 8` |
| `python` | `100` | `8 / 8` |
| `rust` | `100` | `8 / 8` |
| `ts` | `100` | `8 / 8` |

Overall matrix score: `100`
Integration test names scanned: `200`
Test-source scan: `ctest --test-dir build/matrix/ci`
Gating mode: **structural** — coverage is inferred from registered test names. Supply `--ctest-junit` for behavioral (executed pass/fail) gating.

`Mode` meanings:

- `fixture`: category-specific lane(s) exist for this backend/family.
- `corpus`: broad corpus parity lane used as coverage evidence for this family.

## `c`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-signed-narrow-c-python-parity`, `llvmdsdl-signed-narrow-c-python-parity-optimized`, `llvmdsdl-signed-narrow-c-python-parity-runtime-fast`, `llvmdsdl-signed-narrow-c-ts-parity`, `llvmdsdl-signed-narrow-c-ts-parity-optimized` |
| `Fixed array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-fixed-array-parity`, `llvmdsdl-fixtures-c-python-fixed-array-parity-optimized`, `llvmdsdl-fixtures-c-ts-composite-fixed-array-parity` |
| `Variable array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-variable-array-parity`, `llvmdsdl-fixtures-c-python-variable-array-parity-optimized`, `llvmdsdl-fixtures-c-ts-variable-array-parity` |
| `Union` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-union-parity`, `llvmdsdl-fixtures-c-python-union-parity-optimized`, `llvmdsdl-fixtures-c-ts-union-parity` |
| `Delimited` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-delimited-parity`, `llvmdsdl-fixtures-c-python-delimited-parity-optimized`, `llvmdsdl-fixtures-c-ts-delimited-parity` |
| `Service` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-service-parity`, `llvmdsdl-fixtures-c-python-service-parity-optimized`, `llvmdsdl-fixtures-c-ts-service-parity` |
| `Truncated decode` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-truncated-decode-parity`, `llvmdsdl-fixtures-c-python-truncated-decode-parity-optimized`, `llvmdsdl-fixtures-c-ts-truncated-decode-parity` |
| `Padding/alignment` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-padding-alignment-parity`, `llvmdsdl-fixtures-c-python-padding-alignment-parity-optimized`, `llvmdsdl-fixtures-c-ts-padding-alignment-parity` |

## `cpp`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-signed-narrow-cpp-c-parity`, `llvmdsdl-signed-narrow-cpp-c-parity-optimized` |
| `Fixed array` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Variable array` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Union` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Delimited` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Service` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Truncated decode` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |
| `Padding/alignment` | `corpus` | `covered` | `llvmdsdl-uavcan-cpp-c-parity`, `llvmdsdl-uavcan-cpp-c-parity-optimized` |

## `go`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-signed-narrow-c-go-parity`, `llvmdsdl-signed-narrow-c-go-parity-optimized` |
| `Fixed array` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Variable array` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Union` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Delimited` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Service` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Truncated decode` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |
| `Padding/alignment` | `corpus` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-c-go-parity-optimized` |

## `python`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-bigint-parity`, `llvmdsdl-fixtures-c-python-bigint-parity-optimized`, `llvmdsdl-fixtures-c-python-float-parity`, `llvmdsdl-fixtures-c-python-float-parity-optimized`, `llvmdsdl-signed-narrow-c-python-parity`, `llvmdsdl-signed-narrow-c-python-parity-optimized`, `llvmdsdl-signed-narrow-c-python-parity-runtime-fast` |
| `Fixed array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-fixed-array-parity`, `llvmdsdl-fixtures-c-python-fixed-array-parity-optimized` |
| `Variable array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-variable-array-parity`, `llvmdsdl-fixtures-c-python-variable-array-parity-optimized` |
| `Union` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-union-parity`, `llvmdsdl-fixtures-c-python-union-parity-optimized` |
| `Delimited` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-delimited-parity`, `llvmdsdl-fixtures-c-python-delimited-parity-optimized` |
| `Service` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-service-parity`, `llvmdsdl-fixtures-c-python-service-parity-optimized` |
| `Truncated decode` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-truncated-decode-parity`, `llvmdsdl-fixtures-c-python-truncated-decode-parity-optimized` |
| `Padding/alignment` | `fixture` | `covered` | `llvmdsdl-fixtures-c-python-padding-alignment-parity`, `llvmdsdl-fixtures-c-python-padding-alignment-parity-optimized` |

## `rust`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-signed-narrow-c-rust-parity`, `llvmdsdl-signed-narrow-c-rust-parity-inline-then-pool`, `llvmdsdl-signed-narrow-c-rust-parity-no-std-alloc`, `llvmdsdl-signed-narrow-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-signed-narrow-c-rust-parity-optimized`, `llvmdsdl-signed-narrow-c-rust-parity-runtime-fast` |
| `Fixed array` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Variable array` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Union` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Delimited` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Service` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Truncated decode` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |
| `Padding/alignment` | `corpus` | `covered` | `llvmdsdl-uavcan-c-rust-parity`, `llvmdsdl-uavcan-c-rust-parity-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-no-std-alloc`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast`, `llvmdsdl-uavcan-c-rust-parity-no-std-runtime-fast-inline-then-pool`, `llvmdsdl-uavcan-c-rust-parity-optimized`, `llvmdsdl-uavcan-c-rust-parity-runtime-fast` |

## `ts`

| Family | Mode | Status | Evidence |
| --- | --- | --- | --- |
| `Scalar` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-bigint-parity`, `llvmdsdl-fixtures-c-ts-float-parity` |
| `Fixed array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-composite-fixed-array-parity` |
| `Variable array` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-composite-variable-array-parity`, `llvmdsdl-fixtures-c-ts-variable-array-parity` |
| `Union` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-union-array-parity`, `llvmdsdl-fixtures-c-ts-union-composite-parity`, `llvmdsdl-fixtures-c-ts-union-parity` |
| `Delimited` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-delimited-invalid-header-parity`, `llvmdsdl-fixtures-c-ts-delimited-parity` |
| `Service` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-service-parity` |
| `Truncated decode` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-truncated-decode-parity` |
| `Padding/alignment` | `fixture` | `covered` | `llvmdsdl-fixtures-c-ts-padding-alignment-parity` |

## Missing Cells

None.

==================================================================================================
Source: docs/reference/guarantees/malformed-input.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/guarantees/malformed-input/
==================================================================================================

# Malformed-Input Contract Matrix

What each backend is required to do with input it must reject, and which of those requirements are covered by tests.

Generated by `tools/convergence/malformed_contract_matrix_report.py`.

## Summary

| Backend mode family | Score | Covered / Total |
| --- | ---: | ---: |
| `native_c_cpp_go_boundaries` | `100` | `5 / 5` |
| `python_portable_fast_accel` | `100` | `5 / 5` |
| `rust_portable_fast` | `100` | `5 / 5` |
| `ts_portable_fast` | `100` | `5 / 5` |

Overall matrix score: `100`
Integration test names scanned: `200`
Test-source scan: `ctest --test-dir build/matrix/ci`
Gating mode: **structural** — coverage is inferred from registered test names. Supply `--ctest-junit` for behavioral (executed pass/fail) gating.

## `native_c_cpp_go_boundaries`

Native C/C++/Go parity lanes enforce malformed decode/capacity behaviour compatibility.

| Category | Status | Evidence |
| --- | --- | --- |
| `Out-of-range bit read/copy handling` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-cpp-c-parity` |
| `Bit-copy range violation handling` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-cpp-c-parity` |
| `Invalid union-tag handling` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-cpp-c-parity` |
| `Invalid delimited-header handling` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-cpp-c-parity` |
| `Section serialization-capacity precheck` | `covered` | `llvmdsdl-uavcan-c-go-parity`, `llvmdsdl-uavcan-cpp-c-parity` |

## `python_portable_fast_accel`

Mode-specific malformed contract validated (`portable|fast|accel`) with fuzz/parity lanes.

| Category | Status | Evidence |
| --- | --- | --- |
| `Out-of-range bit read/copy handling` | `covered` | `llvmdsdl-fixtures-python-malformed-decode-fuzz-parity`, `llvmdsdl-fixtures-python-malformed-input-contract` |
| `Bit-copy range violation handling` | `covered` | `llvmdsdl-fixtures-python-malformed-decode-fuzz-parity`, `llvmdsdl-fixtures-python-malformed-input-contract` |
| `Invalid union-tag handling` | `covered` | `llvmdsdl-fixtures-c-python-union-parity` |
| `Invalid delimited-header handling` | `covered` | `llvmdsdl-fixtures-c-python-delimited-parity` |
| `Section serialization-capacity precheck` | `covered` | `llvmdsdl-fixtures-python-runtime-parity` |

## `rust_portable_fast`

Rust runtime contract unit tests plus cross-language parity lanes enforce malformed behaviour classes.

| Category | Status | Evidence |
| --- | --- | --- |
| `Out-of-range bit read/copy handling` | `covered` | `llvmdsdl-fixtures-rust-runtime-unit-tests`, `llvmdsdl-fixtures-rust-runtime-unit-tests-no-std-pool` |
| `Bit-copy range violation handling` | `covered` | `llvmdsdl-fixtures-rust-runtime-unit-tests`, `llvmdsdl-fixtures-rust-runtime-unit-tests-no-std-pool` |
| `Invalid union-tag handling` | `covered` | `llvmdsdl-uavcan-c-rust-parity` |
| `Invalid delimited-header handling` | `covered` | `llvmdsdl-uavcan-c-rust-parity` |
| `Section serialization-capacity precheck` | `covered` | `llvmdsdl-fixtures-rust-runtime-unit-tests` |

## `ts_portable_fast`

Error-throwing runtime paths validated by TS smoke/parity lanes.

| Category | Status | Evidence |
| --- | --- | --- |
| `Out-of-range bit read/copy handling` | `covered` | `llvmdsdl-fixtures-c-ts-truncated-decode-parity`, `llvmdsdl-ts-runtime-truncated-decode-smoke` |
| `Bit-copy range violation handling` | `covered` | `llvmdsdl-fixtures-c-ts-truncated-decode-parity`, `llvmdsdl-ts-runtime-truncated-decode-smoke` |
| `Invalid union-tag handling` | `covered` | `llvmdsdl-fixtures-c-ts-union-parity` |
| `Invalid delimited-header handling` | `covered` | `llvmdsdl-fixtures-c-ts-delimited-invalid-header-parity`, `llvmdsdl-ts-runtime-delimited-invalid-header-smoke` |
| `Section serialization-capacity precheck` | `covered` | `llvmdsdl-fixtures-c-ts-runtime-parity` |

## Missing Cells

None.

## Native Behaviour Guards

All checks passed: `True`

| Guard | Status | Notes |
| --- | --- | --- |
| `c_go_directed_coverage_summary` | `pass` | script `test/integration/RunCGoParity.cmake` |
| `c_rust_directed_markers` | `pass` | script `test/integration/RunCRustParity.cmake` |
| `cpp_c_directed_markers` | `pass` | script `test/integration/RunCppCParity.cmake` |
| `cpp_c_vs_c_rust_marker_alignment` | `pass` | - |

==================================================================================================
Source: docs/reference/guarantees/determinism.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/guarantees/determinism/
==================================================================================================

# Determinism Matrix Coverage

Which axes of generated output are required to be byte-reproducible — across repeated runs, hosts, and toolchains — and which of those requirements are covered by tests.

Generated by `tools/convergence/determinism_matrix_report.py`.

## Summary

| Backend | Status | Evidence |
| --- | --- | --- |
| `c` | `covered` | `llvmdsdl-uavcan-c-determinism` |
| `cpp` | `covered` | `llvmdsdl-uavcan-cpp-determinism` |
| `go` | `covered` | `llvmdsdl-uavcan-go-determinism` |
| `python` | `covered` | `llvmdsdl-uavcan-python-determinism` |
| `rust` | `covered` | `llvmdsdl-uavcan-rust-determinism-inline-then-pool` |
| `ts` | `covered` | `llvmdsdl-uavcan-ts-determinism` |

Overall matrix score: `100`
Integration test names scanned: `200`
Test-source scan: `ctest --test-dir build/matrix/ci`
Gating mode: **structural** — coverage is inferred from registered test names. Supply `--ctest-junit` for behavioral (executed pass/fail) gating.

## Missing Backends

None.

==================================================================================================
Source: docs/reference/guarantees/supply-chain.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/reference/guarantees/supply-chain/
==================================================================================================

# Supply chain: SBOM and the LLVM version lock

Two related release-mechanics concerns: what a release artifact is *made of* (the SBOM), and why the
LLVM/MLIR major version it links against is *pinned* (the version lock).

## SBOM

Every build emits a [CycloneDX 1.5](https://cyclonedx.org/) SBOM describing the release artifacts.

- **Generated by:** `cmake/GenerateSBOM.cmake`, driven by the `sbom` target, which is part of `ALL`.
- **Build tree:** `<build>/llvm-dsdl-sbom.cdx.json`
- **Installed to:** `<prefix>/<datadir>/llvm-dsdl/llvm-dsdl-sbom.cdx.json` (component `bin`)
- **Regenerate on demand:** `cmake --build <build> --target sbom`

### Contents

| Component | Scope | Why |
| --- | --- | --- |
| `llvm-dsdl` (metadata component) | — | Tool version (from `VERSION`), MIT, the shipped tool names, and the **exact source commit** under `pedigree.commits` |
| `llvm`, `mlir` | `required` | The LLVM/MLIR actually found by `find_package` and linked into the tools |
| `zstd` | `required` (when found) | Pulled in transitively by LLVM |
| `llvm-dsdl-runtime` | `required` | First-party serialization runtime shipped as headers/sources alongside generated code |
| `public_regulated_data_types`, `libudpard` | `excluded` | Submodules pinned to exact commits. They are **build/test inputs** (the DSDL corpus; libudpard for the examples) and are *not* linked into shipped artifacts — recorded for provenance, scoped out of the shipped dependency set |

### Determinism

The generator emits **no wall-clock timestamp and no random serial number**, so regenerating from the
same commit produces a byte-identical document. For a timestamped document, pass
`-DSOURCE_DATE_EPOCH_VALUE=<epoch>` to the generator.

If the source tree is not a git checkout (e.g. an extracted tarball), the SBOM is still valid — the
commit is recorded as `unknown` and submodule entries are omitted.

## LLVM version lock

**Policy: the LLVM/MLIR major version is locked (currently 22).**

### Why

The C backend is routed through MLIR/EmitC, whose printed output can legitimately vary across MLIR
majors. The same DSDL compiled against two different MLIR majors may produce C that differs textually
while remaining semantically equivalent, which makes the LLVM major a semantic input to the output
rather than a build detail.

### Where it is enforced

The lock is enforced **at configure time** by the build system and **again** by CI.

- **Build system:** after `find_package(LLVM/MLIR)`, CMake asserts `LLVM_VERSION_MAJOR` equals
  `LLVMDSDL_REQUIRED_LLVM_MAJOR` (currently `22`) and fails configuration otherwise.
  `-DLLVMDSDL_ALLOW_LLVM_MAJOR_MISMATCH=ON` downgrades the failure to a warning. MLIR ships with LLVM
  at the same version, so asserting the LLVM major covers MLIR too.
- **Linux (x86-64, libstdc++):** `LLVM_DIR`/`MLIR_DIR`/`CMAKE_PREFIX_PATH` pin `/usr/lib/llvm-22`, and
  the determinism job records the real version via `llvm-config --version` into the corpus-hash
  manifest (`--meta llvm=…`).
- **macOS (arm64, libc++):** Homebrew `llvm@22`, with an asserted major.
- **Cross-stdlib determinism lane:** `tools/determinism/cross_stdlib_corpus_hash.py` compares the two
  hosts' recorded LLVM majors. CI passes `--require-c`, which makes a major skew a **hard failure**.

### Consequences

- Build against the locked major to reproduce released artifacts byte-for-byte.
- The SBOM records the LLVM/MLIR version *actually linked*.
- To raise the lock: bump `LLVMDSDL_REQUIRED_LLVM_MAJOR` and the CI pins together (both hosts must move
  at once, or `--require-c` fails), then re-baseline the determinism corpus hashes.

==================================================================================================
Source: docs/showroom/index.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/showroom/
==================================================================================================

# Showroom

One namespace of plausible vendor-specific datatypes for an aerial drone system, and everything
dsdlc does with it -- generated into every language and profile the compiler supports, and then
built by thirteen real build systems.

It exists so you can answer three questions in order, without inventing a schema of your own:

1. **What would I write?** `lanyard` is a fictional vendor's namespace, the sort of thing a drone
   programme adds alongside the standard `uavcan` types. Nothing here is regulated and UDRAL is
   deliberately unused -- the point is what a vendor writes from scratch, leaning on the standard
   types where standard types exist.
2. **What does the compiler make of it?** Every definition below pairs its authored DSDL with its
   wire-layout facts and a declaration excerpt in each language.
3. **How do I get that into my build?** The same namespace, wired into CMake, Make, Ninja
   Multi-Config, Bazel, cargo, go modules, npm, pnpm, and five Python build backends. See
   **[Build Recipes](recipes/index.md)**.

The two halves make opposite bets on purpose. Browsing generates and stops -- it must never fail for
a reason unrelated to what it is showing. The recipes compile and run, because a recipe that did not
build would prove nothing.

## Generate it

```bash
cmake --build <build-dir> --target showroom
```

Output lands in `<build-dir>/showroom/<variant>/`:

| Variant | Command |
|---|---|
| `c` | `--target-language c` |
| `cpp-std`, `cpp-pmr`, `cpp-autosar` | `--target-language cpp --cpp-profile <profile>` |
| `rust-std`, `rust-no-std-alloc` | `--target-language rust --rust-profile <profile>` |
| `go` | `--target-language go` |
| `ts` | `--target-language ts` |
| `python` | `--target-language python` |
| `mlir` | `--target-language mlir` (the intermediate form, one file) |

Nothing here is compiled -- correctness of the generated code is what `test/lit` and the integration
suites are for, and compiling would make browsing depend on six language toolchains being present.
Building the output is what the [recipes](recipes/index.md) do, deliberately as a separate half.

Individual variants build on their own: `cmake --build <build-dir> --target showroom-rust-std`.

There is no submodule dependency -- `lanyard` refers only to `uavcan` types, which dsdlc carries in
its embedded catalog.

## Contents

Twenty-four definitions across six sub-namespaces, chosen so that between them they exercise the
language and the three LEAST SUPPORTED TRANSPORTs a real vehicle spans.

| Type | Port | Least supported transport | Kind |
|---|---:|---|---|
| [`lanyard.flight.ControlSurfaces.1.0`](types/lanyard_flight_ControlSurfaces_1_0.md) | 6212 | CAN FD | message |
| [`lanyard.flight.FixedWingSurfaces.1.0`](types/lanyard_flight_FixedWingSurfaces_1_0.md) | -- | unspecified | message |
| [`lanyard.flight.FlightMode.1.0`](types/lanyard_flight_FlightMode_1_0.md) | -- | unspecified | message |
| [`lanyard.flight.MultirotorMix.1.0`](types/lanyard_flight_MultirotorMix_1_0.md) | -- | unspecified | message |
| [`lanyard.flight.VehicleState.1.0`](types/lanyard_flight_VehicleState_1_0.md) | 6210 | CAN FD | message |
| [`lanyard.flight.VehicleState.1.1`](types/lanyard_flight_VehicleState_1_1.md) | 6210 | CAN FD | message |
| [`lanyard.flight.VehicleState.2.0`](types/lanyard_flight_VehicleState_2_0.md) | 6211 | CAN FD | message |
| [`lanyard.health.BatteryStatus.2.0`](types/lanyard_health_BatteryStatus_2_0.md) | 6251 | CAN FD | message |
| [`lanyard.health.LegacyBatteryPoll.1.0`](types/lanyard_health_LegacyBatteryPoll_1_0.md) | 258 | Classic CAN | service |
| [`lanyard.health.SubsystemReport.1.0`](types/lanyard_health_SubsystemReport_1_0.md) | -- | unspecified | message |
| [`lanyard.health.SystemHealth.1.0`](types/lanyard_health_SystemHealth_1_0.md) | 6250 | CAN FD | message |
| [`lanyard.link.RcInput.1.0`](types/lanyard_link_RcInput_1_0.md) | 6240 | CAN FD | message |
| [`lanyard.link.TelemetryLinkStats.1.0`](types/lanyard_link_TelemetryLinkStats_1_0.md) | 6241 | CAN FD | message |
| [`lanyard.nav.GlobalPosition.1.0`](types/lanyard_nav_GlobalPosition_1_0.md) | 6220 | CAN FD | message |
| [`lanyard.nav.MissionPlan.1.0`](types/lanyard_nav_MissionPlan_1_0.md) | 6221 | Cyphal/UDP ONLY | message |
| [`lanyard.nav.UploadMission.1.0`](types/lanyard_nav_UploadMission_1_0.md) | 256 | CAN FD and Cyphal/UDP | service |
| [`lanyard.nav.Waypoint.1.0`](types/lanyard_nav_Waypoint_1_0.md) | -- | unspecified | message |
| [`lanyard.payload.CameraFrameMetadata.1.0`](types/lanyard_payload_CameraFrameMetadata_1_0.md) | 6231 | Cyphal/UDP ONLY | message |
| [`lanyard.payload.CapturePhoto.1.0`](types/lanyard_payload_CapturePhoto_1_0.md) | 257 | CAN FD and Cyphal/UDP | service |
| [`lanyard.payload.GimbalStatus.1.0`](types/lanyard_payload_GimbalStatus_1_0.md) | 6230 | CAN FD | message |
| [`lanyard.propulsion.EscStatus.1.0`](types/lanyard_propulsion_EscStatus_1_0.md) | 6200 | Classic CAN (CAN 2.0B) | message |
| [`lanyard.propulsion.EscStatus.2.0`](types/lanyard_propulsion_EscStatus_2_0.md) | 6201 | CAN FD | message |
| [`lanyard.propulsion.ThrottleCommand.0.1`](types/lanyard_propulsion_ThrottleCommand_0_1.md) | 6202 | CAN FD | message |
| [`lanyard.propulsion.ThrottleCommand.1.0`](types/lanyard_propulsion_ThrottleCommand_1_0.md) | 6203 | CAN FD | message |

## Least Supported Transport

Every definition states a minimally capable transport it was sized for, and most of them assert that
budget with `@assert _offset_.max <= ...` so that a layout change breaks the build rather than
quietly spilling into a multi-frame transfer. Cyphal does not limit DSDL by transport but type
authors often make different design choices based on the limitations of certain transports. In some
cases these design choices are not clear unless these limitations are called out in type comments or
by using DSDL assert statements.

| Transport | Budget | Examples |
|---|---|---|
| Classic CAN | 7 payload bytes, one frame | `propulsion.EscStatus.1.0`, hand-packed to exactly 56 bits |
| CAN FD | 63 payload bytes, one frame | `nav.GlobalPosition.1.0`, `link.RcInput.1.0`, `payload.GimbalStatus.1.0` |
| Cyphal/UDP | a datagram, kilobytes | `nav.MissionPlan.1.0`, `payload.CameraFrameMetadata.1.0` |

`EscStatus.1.0` and `MissionPlan.1.0` are the two ends of that range on purpose: same compiler, same
language, one sized for a 7-byte frame and the other for a 24 KiB datagram.

### Versioning

Five migrations, each answering a different question about when a change forces a major bump.

| Transition | Breaking | What it shows |
|---|---|---|
| `ThrottleCommand` 0.1 → 1.0 | n/a | A `0.x` definition promises nothing; promotion to 1.0 is where the promise begins |
| `VehicleState` 1.0 → 1.1 | no | A field appended inside an unchanged `@extent`; both share port 6210 |
| `VehicleState` 1.1 → 2.0 | yes | A field retyped, a field replaced, the extent grown; new port 6211 |
| `EscStatus` 1.0 → 2.0 | yes | `@sealed` is a one-way door: extensibility costs a major version |
| `LegacyBatteryPoll` 1.0 → `BatteryStatus` 2.0 | yes | `@deprecated` marking a superseded service, both halves kept |

### Language features

| Feature | Where |
|---|---|
| `@sealed` | `EscStatus.1.0`, `RcInput.1.0`, `SubsystemReport.1.0` |
| `@extent` | `VehicleState.1.0`, `MissionPlan.1.0`, `Waypoint.1.0` |
| `@union` | `ControlSurfaces.1.0` |
| `@assert` | `EscStatus.1.0`, `GlobalPosition.1.0`, `CapturePhoto.1.0` |
| `@print` | `GlobalPosition.1.0` |
| `@deprecated` | `LegacyBatteryPoll.1.0` |
| Service request/response sections | `UploadMission.1.0`, `CapturePhoto.1.0` |
| Non-byte-aligned scalars | `EscStatus.1.0` (`uint14`, `int12`, `int9`, `uint4`) |
| `void` padding | `EscStatus.1.0`, `GlobalPosition.1.0`, `SubsystemReport.1.0` |
| Fixed-size arrays | `GlobalPosition.1.0` (`float16[9]`), `RcInput.1.0` (`uint11[16]`) |
| Variable-length arrays | `ThrottleCommand.1.0`, `MissionPlan.1.0`, `BatteryStatus.2.0` |
| Arrays of composites | `MissionPlan.1.0` (delimited elements), `SystemHealth.1.0` (sealed elements) |
| Cast modes | `CameraFrameMetadata.1.0` (`truncated` against `saturated`) |
| Constants as enumerations | `FlightMode.1.0`, `Waypoint.1.0`, `GlobalPosition.1.0` |
| Reuse of standard `uavcan` types | throughout; `SubsystemReport.1.0` is the clearest case |

## Documentation

DSDL comment placement follows the OpenCyphal convention used by the regulated namespace: **the
block goes after the attribute it documents, followed by a blank line.** A block placed *before* a
field attaches to whatever precedes it instead, or is absorbed into the type's own documentation if
the field is the first one.

`@deprecated` rides along with it. Every backend appends a `Deprecated: …` notice to the type's
documentation and emits an `IS_DEPRECATED` constant. Go treats the notice as a real deprecation, and
TypeScript additionally gets a `/** @deprecated */` JSDoc block.

C, C++, and Rust get compile-time enforcement on top of that, by default:
`__attribute__((deprecated))`, `[[deprecated]]`, and `#[deprecated]`. Only code that names a
deprecated type is diagnosed — each generated file suppresses the diagnostic across its own body, so
including the headers stays clean under `-Werror`. `dsdlc --no-deprecation-attributes` drops the
attributes. See `health/258.LegacyBatteryPoll.1.0.dsdl`.

## Port identifiers

`lanyard` is not a standard root namespace, so its fixed port identifiers come from the unregulated
ranges: **6144–7167 for messages** and **256–383 for services**. Staying inside them is what lets
the showroom build without `--allow-unregulated-fixed-port-id`.

A fixed port identifier belongs to one major version. Minor versions share it (`VehicleState.1.0`
and `1.1` are both on 6210); a major bump takes a new one (`VehicleState.2.0` moves to 6211).

==================================================================================================
Source: docs/showroom/recipes/index.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/showroom/recipes/
==================================================================================================

# Build Recipes

The [showroom](../index.md) shows you what dsdlc produces from the `lanyard` namespace. This is the
other half: the build wiring that turns that output into a compiled library.

Each *recipe* is one (language, build system) pair, complete and self-contained, and every one
builds the same twenty-four definitions you can browse on the [overview](../index.md). Browsing a type
and then seeing it compiled into a library is the point of the two halves living together.

A recipe generates with `dsdlc`, compiles the output, and runs a round-trip program that serialises
a value, deserialises it, and checks the result. CI runs all of them, so a recipe on this page is a
recipe that worked the last time anyone looked -- which is the one thing the browsing half
deliberately does not promise, since it generates and stops.

## Self-contained output

**Generated output is self-contained.** The language runtime is embedded in `dsdlc` and written into
your output directory alongside the generated types. There is no runtime package to add to your
manifest, no version to keep in step, and no second thing to install. Point `dsdlc` at a namespace,
compile what comes out.

For Rust, Go, TypeScript, and Python, `dsdlc` goes further and writes a native manifest too --
`Cargo.toml`, `go.mod`, `package.json`, `pyproject.toml`. C and C++ get `dsdl_runtime.h` /
`dsdl_runtime.hpp` and no manifest, because C and C++ have no such thing to write.

## Two idioms

Every recipe is one of two shapes. Which one you get is decided by your build system, not by taste.

**Idiom A -- the generated tree *is* the package.** Your build depends on it by path: a cargo path
dependency, a `go.mod` `replace` directive, `pip install -e`. The manifest `dsdlc` wrote is the one
that gets used. Shortest path when it is available, which for Rust and Go is a single line.

**Idiom B -- your project owns the manifest; the generated tree is sources.** You point your
existing build at the output directory and compile it as part of your own target. Forced on you
when:

- **C and C++** -- no manifest is emitted at all, because neither language has one to emit.
- **TypeScript** -- a `package.json` *is* emitted, but it declares no `main`, `exports`, or `types`
and the tree contains only `.ts` files. `npm install file:generated` succeeds and then fails at run
time, because Node falls back to looking for `index.js` and finds `index.ts`. Generated TypeScript
is source, and joins your program as source.
- **Every Python build backend except setuptools** -- the emitted `pyproject.toml` declares
  `setuptools.build_meta`, and a project cannot have two build backends. Pointing another backend at
  the generated package is one line of configuration; the generated tree is an ordinary Python
  package, and dsdlc's own manifest just sits there unused.

Each recipe page states which idiom it is and why that build system left no choice.

## Keeping generated code fresh

The second decision every recipe makes, independent of the idiom: how does the build know to
regenerate? Getting this wrong is how a build serves stale generated code after a schema edit.

| Strategy | Mechanism | Precision | Suits |
|---|---|---|---|
| Configure-time query | `--list-outputs`, `--list-inputs` | Exact | CMake, Make |
| Build-time depfile | `-MD` | Exact, incremental | Make, Ninja, Bazel |
| Stamp file | One sentinel output | Coarse | Fallback |

`--list-outputs` and `--list-inputs` print a semicolon-separated list and imply `--dry-run`, so a
build can ask what *would* be produced before producing it. `-MD` writes make-style `.d` files next
to the generated output. Between them, an exact incremental integration is available in any build
system that can run a command at configure time or read a depfile -- which is all of them.

## Splitting generation up

You are not obliged to treat a namespace as one indivisible run. dsdlc will tell you what it would
emit for any subset of its work, which means a build can give each subset its own rule, its own
outputs, and its own lifetime.

| Selector | Selects |
|---|---|
| `--generate-support only` | Only code *not* derived from a definition: runtime headers and modules, package manifests, scaffolding. Needs no positional target. |
| `--generate-support never` | Only code derived from definitions. |
| `--omit-dependencies` | Only the definitions named, not the ones they refer to. |
| `+uavcan.node`, `+uavcan.node.Heartbeat.1.0` | Standard types from the catalog compiled into `dsdlc`, with no checkout of `public_regulated_data_types`. |
| `<root>:<relative/Type.1.0.dsdl>` | One definition, with output paths anchored at `<root>`. |

Combining them gives a build as much granularity as it wants -- per namespace, per tranche, or per
definition. The reason to bother is that these things change at different rates: the runtime header
and the standard types move only when the compiler does, while your own definitions change all day.
Split along that line and editing a definition rebuilds one archive instead of all of them, and the
standard types become a library that several components share.

**Past one namespace this stops being an optimisation and becomes a requirement.** Two runs that
both default to `--generate-support as-needed` into the same output directory both emit the runtime
header, and two rules producing one file is an error Ninja refuses to build at all. The same goes
for a standard type two namespaces both refer to. So a project with several namespaces gives support
one owner, the shared standard types another, and passes `--omit-dependencies` to the rest.

The [GNU Make recipe](c-make.md) is built this way, in three tranches. `dsdlc_generate()`
takes `SUPPORT`, `BUILTIN`, and `OMIT_DEPENDENCIES` for the same purpose, and refuses at configure
time -- naming both claimants -- if two calls would produce the same file.

The requirement is about *sharing an output directory*, not about having several namespaces. A build
that gives each namespace its own output tree never collides and never needs the split -- which is
what the [Bazel](c-bazel.md) fetch-time path does, one external repository per namespace.
The split is what you need when several runs write into one tree.

### Prebuilt archives

`-l obj` is the other shape: it runs the C backend and then compiles it, handing back objects and a
`.a`. Use it when the generated code should be built once -- for a target triple that is not the
host, or by a party who ships the archive rather than the schema. The archive then only links into a
build using that same toolchain.

The headers are published beside the archive, in the same layout the `c` backend uses, so one
invocation gives a complete interface -- add the output directory to your include path and link the
archive. The [CMake](c-cmake.md) and [Bazel](c-bazel.md) recipes both build one.

### Deleting a definition

Generation adds files; it does not remove them. Delete a definition and its generated header stays
in the output directory, still on the include path, so code naming a type nobody defines any more
keeps compiling.

`--prune-manifest <file>` fixes that: the run records what it produced and, next time, deletes what
it no longer produces. One manifest per invocation, never one per directory -- a tranche owns only
the files it emits, and one that swept the output directory would delete its siblings' work.
`dsdlc_generate()` passes one automatically.

**If your build has to reshape what dsdlc emits, that is a bug worth reporting rather than a recipe
worth copying.** Nothing on these pages moves, renames, or post-processes a generated file, and no
recipe should need to.

## The matrix

| Language | Build system | Idiom | Regeneration |
|---|---|---|---|
| C / C++ | [Bazel](c-bazel.md) | B | None -- regeneration is an explicit step |
| C / C++ | [CMake](c-cmake.md) | B | Configure-time query (`--list-outputs`) |
| C / C++ | [CMake + Ninja Multi-Config](c-cmake-ninja-multi.md) | B | Configure-time query (`--list-outputs`) |
| C / C++ | [GNU Make](c-make.md) | B | Build-time depfile (`-MD`) |
| Go | [go modules](go-modules.md) | A | None -- regeneration is an explicit step |
| Python | [flit](py-flit.md) | B | None -- regeneration is an explicit step |
| Python | [hatchling](py-hatchling.md) | B | None -- regeneration is an explicit step |
| Python | [poetry](py-poetry.md) | B | None -- regeneration is an explicit step |
| Python | [setuptools](py-setuptools.md) | A | None -- regeneration is an explicit step |
| Python | [uv-build](py-uv-build.md) | B | None -- regeneration is an explicit step |
| Rust | [cargo](rust-cargo.md) | A | None -- regeneration is an explicit step |
| TypeScript | [npm](ts-npm.md) | B | None -- regeneration is an explicit step |
| TypeScript | [pnpm](ts-pnpm.md) | B | None -- regeneration is an explicit step |

## Running a recipe yourself

Every recipe directory is independently runnable. Copy the recipe you want plus `dsdl/` and `src/`
alongside it, and run the commands on its page. The CI runner stages exactly that copy for every
recipe on every run.

To run them from a checkout:

```bash
python3 examples/showroom/run_recipe.py --dsdlc /path/to/dsdlc
```

Add recipe names to run a subset, `--list` to see what is registered, and `--verbose` to watch the
commands.

## Prerequisites

Each recipe page lists the tools that recipe needs, and `run_recipe.py` skips a recipe whose tools
are absent rather than failing it. No recipe installs anything into your system: the Python recipes
each build a virtual environment and fetch their own build backend, which is both correct isolation
and the only thing that works on a distribution that marks its interpreter externally managed (PEP
668).

## The recipe invariant

**Recipes contain build wiring and nothing else.** The round-trip programs live in `src/`, one per
language, shared by every recipe in that row; the schema lives in `dsdl/`, shared by all of them.

So the difference between the poetry recipe and the hatchling recipe is *only* the build files --
which is the comparison the recipes exist to support. `run_recipe.py --check-invariant` enforces
it, and CI runs that check.

## What the recipes build

Every recipe builds the whole `lanyard` namespace: thirty-six translation units in C once the
standard types it reaches are counted, and it costs about four seconds across the whole matrix.
Measured rather than assumed: generation is ~70 ms per backend, and the compile cost is what
dominates, only where a recipe builds serially.

Between them the definitions force a real integration:

| What | Why it matters |
|---|---|
| Twelve standard `uavcan` types, reached transitively | They resolve from the catalog compiled into dsdlc -- no checkout of `public_regulated_data_types` anywhere in the matrix |
| Three different `Vector3` types in sibling namespaces | Same short name, different namespace: the case that breaks a naive import |
| Two `@deprecated` definitions | A namespace containing them still has to compile clean |
| Services, unions, multiple versions of one type | Each generates more than one type from one file |

An integration that compiles `SystemHealth` but not the `SubsystemReport` it embeds is broken, and
this namespace is shaped to fail loudly when that happens.

==================================================================================================
Source: docs/development/contributing.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/contributing/
==================================================================================================

# Contributing

How to build the compiler, run its gates, and get a change accepted. This page is the short form;
`CONTRIBUTING.md` in the repository is the long one and takes precedence where they differ.

For complete developer workflow details, start with:

- [CONTRIBUTING.md](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/CONTRIBUTING.md)

## Fast path

```bash
git clone https://github.com/OpenCyphal-Garage/llvm-dsdl.git
cd llvm-dsdl
git submodule update --init --recursive
cmake --preset ci
cmake --build --preset build-ci
ctest --preset test-ci-smoke
```

## Quality checks

- `check-format`
- `check-clang-tidy`
- `check-iwyu`
- integration and release-blocking presets

Keep behavioral parity and matrix CI green before merge.

==================================================================================================
Source: docs/development/testing.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/testing/
==================================================================================================

# Testing and CI

`llvm-dsdl` uses layered test gates:

- unit tests
- lit tests
- integration smoke/parity tests
- release-blocking lanes

## Common commands

```bash
ctest --preset test-ci-smoke
ctest --preset test-ci-full
ctest --preset test-ci-release-blocking
```

## Targeted runs

```bash
ctest --test-dir build/matrix/ci -C RelWithDebInfo -R llvmdsdl-lit --output-on-failure
ctest --test-dir build/matrix/ci -C RelWithDebInfo -R llvmdsdl-obj-backend-smoke --output-on-failure
```

## Docs site CI

A dedicated GitHub Pages workflow builds this manual with MkDocs Material and deploys on `main`.

See `.github/workflows/docs.yml`.

==================================================================================================
Source: docs/development/architecture.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/architecture/
==================================================================================================

# Architecture

`llvm-dsdl` compiles DSDL through a shared semantic core and a custom MLIR dialect.

```mermaid
flowchart LR
  A[".dsdl files"] --> B["Frontend\n(discovery + parser)"]
  B --> C["Semantic analysis"]
  C --> D["DSDL MLIR dialect"]
  D --> E["Executable lowering + validation passes"]
  E --> F{"Backend emitters"}
  F --> G["C/C++/Rust/Go/TS/Python"]
  F --> H["obj (.o/.a)"]
```

## Why this shape

- Single source of truth for semantics
- Strong pass and contract boundaries
- Better backend parity and testability

## The dialect is the contract boundary

The custom `dsdl` MLIR dialect is what separates frontend semantics from backend rendering. Everything
above it decides what a definition *means*; everything below it decides how that meaning is spelled in
a particular language.

- Schema and serialization plans are represented as explicit IR ops
- Passes stamp and validate lowered contract metadata
- Backends consume facts from validated lowered state, never from raw IR

### Pass sequence

1. `lower-dsdl-exec`
2. `dsdl-annotate-aliasability` — conservative aliasability *annotator*; stamps metadata only
3. `dsdl-legalize-endianness` — validates and stamps target endianness; performs no byte reordering
4. optional optimization pipeline

### Boundary guarantees

- Raw or unlowered IR reaching a backend is caught by a contract version and producer-identity guard.
  That guard detects *unlowered state*, not field-level semantic-compatibility drift.
- Backend emitters stay aligned, because they read the same validated facts.
- Unsupported and malformed states produce deterministic diagnostics.

The serialize/deserialize step order the emitters render from this state is itself a contract, and a
published one: see [Emit Order](../reference/codegen/emit-order.md).

## Canonical references

- Design source: [DESIGN.md](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/DESIGN.md)
- Dialect definitions: `include/llvmdsdl/IR/*`
- Transform passes: `include/llvmdsdl/Transforms/*`, `lib/Transforms/*`
- Lowered contract: `include/llvmdsdl/Transforms/LoweredSerDesContract.h`,
  `lib/Transforms/LoweredSerDesContractValidation.cpp`, `lib/CodeGen/MlirLoweredFacts.cpp`

==================================================================================================
Source: docs/development/lint-rule-authoring.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/lint-rule-authoring/
==================================================================================================

# LSP Lint Rule Authoring Guide

This guide explains how to add, test, and ship lint rules for `dsdld`.
For baseline rule catalog and suppression schema, see `docs/reference/lsp/lint-rules.md`.

## 1. Architecture

Primary interfaces:

1. `include/llvmdsdl/LSP/Lint.h`
2. `lib/LSP/Lint.cpp`
3. `test/unit/LspLintTests.cpp`

Key types:

1. `LintRule`: one deterministic rule unit.
2. `LintFinding`: one emitted finding with optional fix edits.
3. `LintRegistry`: rule registration and plugin loading.
4. `LintEngine`: execution and suppression filtering.

## 2. Rule Design Checklist

Before coding, define:

1. Stable rule ID (for suppression/config compatibility).
2. Severity (`Info`, `Warning`, `Error`).
3. Deterministic ordering behaviour.
4. Fix safety (if emitting autofix edits).
5. Scope (statement-level, file-level, namespace-level).

## 3. Adding A Built-In Rule

### 3.1 Implement the rule class

Add a `LintRule` subclass in `lib/LSP/Lint.cpp`:

```cpp
class ExampleRule final : public LintRule
{
public:
    [[nodiscard]] std::string id() const override
    {
        return "example.rule_id";
    }

    [[nodiscard]] std::string title() const override
    {
        return "Example lint rule";
    }

    void run(const LintDocument& document, std::vector<LintFinding>& findings) const override
    {
        // Analyze document.ast and/or document.sourceText.
        // Append deterministic findings.
    }
};
```

### 3.2 Register factory

In `registerBuiltinRules(LintRegistry&)`, add:

```cpp
registry.registerRuleFactory([]() { return std::make_unique<ExampleRule>(); });
```

### 3.3 Keep output deterministic

Use stable iteration order and stable location sorting behaviour.
Avoid non-deterministic containers as final emit order without sorting.

## 4. Autofix Rules

Set these on a finding when fix is available:

1. `finding.hasFix = true`
2. `finding.preferredFix = true` when this should be first quick-fix choice
3. Populate `finding.fixes` with `LintFixEdit` entries

Each edit is `(line, character, length, newText)` in zero-based coordinates.

Guidelines:

1. Emit minimal edits.
2. Avoid overlapping edits in one finding.
3. Keep fix idempotent where practical.
4. Do not alter semantics unless rule is explicitly semantic.

## 5. Suppression Compatibility

Your rule ID participates in all suppression surfaces:

1. Workspace settings: `lint.disabledRules`
2. Per-file settings: `lint.fileSuppressions`
3. Source comment: `# dsdld-lint-disable: <rule-id>`

Use a stable ID because users may persist suppressions in repositories.

## 6. Testing Requirements

Update or add tests in `test/unit/LspLintTests.cpp`:

1. Rule fires on expected fixture.
2. Rule does not fire on conformant fixture.
3. Autofix payload (if any) matches expected edits.
4. Suppression behaviour works.
5. Determinism check remains stable.

If diagnostics goldens are affected, update:

- `test/unit/lint/golden/lint_fixture_diagnostics.golden`

Run:

```bash
cmake --build build/matrix/dev-homebrew --config RelWithDebInfo --target llvmdsdl-unit-tests
build/matrix/dev-homebrew/test/unit/RelWithDebInfo/llvmdsdl-unit-tests
```

## 7. Plugin Rule Packs

`LintRegistry` supports dynamic rule loading. Plugin library must export:

```cpp
extern "C" void llvmdsdlRegisterLintRules(llvmdsdl::lsp::LintRegistry& registry);
```

Inside that function, register one or more factories.

Runtime configuration path:

1. Set `lint.pluginLibraries` in `workspace/didChangeConfiguration`.
2. `LintEngine` loads the libraries during construction.

Current implementation uses `dlopen`/`dlsym` (POSIX dynamic loading).

## 8. Documentation Requirements For New Rules

When adding/removing/changing rules:

1. Update `docs/reference/lsp/lint-rules.md` baseline list and behaviour notes.
2. Mention autofix behaviour if applicable.
3. Add migration notes if rule IDs changed.

## 9. Review Gate

A lint-rule change is ready when:

1. Unit tests pass.
2. Diagnostics remain deterministic.
3. Suppression surfaces behave as documented.
4. Rule documentation is updated.

==================================================================================================
Source: docs/development/roadmap.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/roadmap/
==================================================================================================

# llvm-dsdl — Deep Architectural Review & Production-Readiness Report Card

> _Generated 2026-06-28 against commit `c18867a`. Source references are written as
> `path:line` for the tree at review time; line numbers will drift as the code
> evolves. This document is intended to be committed and iterated on — update
> verdicts and check off roadmap items as the gaps close._

> **Update 2026-07-03 — P0 "Truthful assurance docs" + "Behavioral gates" landed.**
> Work done in this pass, plus corrections to this report where the original review was
> itself stale or overstated (verified against the current tree):
> - **CI is committed** (`​.github/workflows/ci.yml`, `coverage.yml`, `docs.yml`) and the
>   report gates already **hard-fail the build** (`message(FATAL_ERROR …)` in the
>   `cmake/Run*Report.cmake` wrappers, run by the `release-blocking-report-gates` target).
>   G8 / rec 9's "CI uncommitted" and G4/G5's "gates are theater" premises were stale.
> - **Behavioral gates:** the parity, malformed-input, and determinism scorecards now
>   consume **executed ctest pass/fail** (JUnit), not `ctest -N` test-name presence — a
>   cell is `covered` only if a matching test ran and passed (fail/skip/absent ⇒ uncovered).
>   The convergence scorecard is **relabeled** as an infrastructure-consistency lint (it is
>   inherently a marker check and cannot be made behavioral cheaply). See §5 P0.
> - **Passes renamed/redescribed:** `dsdl-prove-zero-overhead` → `dsdl-annotate-aliasability`
>   (drops "proof" language; it is a conservative annotator); `dsdl-legalize-endianness`
>   documented as validation-only (no byte reordering).
> - **Big-endian is NOT "unimplemented".** The original G5/G6/§3 "big-endian absent /
>   needs byte-swap" claim is **overstated** — see the corrected notes below. DSDL wire is
>   always little-endian, `serialize_`/`deserialize_` are host-endianness-agnostic, and the
>   `-l obj … --target-endianness big` smoke test asserts big==little byte-parity; only the
>   zero-copy *view* fast-path is (correctly) disabled on big-endian targets.

**Scope reviewed:** ~45k LOC C++ (`lib/`, `include/`, `tools/`), ~3.6k LOC multi-language runtime, ~17k LOC tests, the MLIR `dsdl` dialect, 6 codegen backends, the LSP, and the build/CI/convergence tooling. Method: docs read first (DESIGN.md, the design pages under `docs/`, the four matrix docs), then implementation, then **adversarial verification of every headline claim** against the actual code. Version under review: **`0.1.0`**.

## 1. Verdict

This is a **genuinely sophisticated advanced prototype** — far above the median "code generator" — built by someone who understands compilers. The MLIR investment is real, the frontend is hardened, the runtime read-path inherits battle-tested bounds-safety, and there is a real differential-testing culture.

But there is a consistent, structural problem that dominates the production-readiness assessment:

> **The assurance *narrative* substantially overstates what the implementation *proves*.** "Convergence = 100," "zero-overhead proof," "producer/consumer drift detection," "verifier-first invariant enforcement," "fallback-free," and "release-blocking malformed/parity gates" are presented as guarantees. On inspection, the three headline scorecards are **marker-presence / test-name-presence metrics**, two of the headline passes are **annotators/validators with grandiose names**, and the strongest assurance claim (differential parity against the reference compiler) covers **5 hand-picked types and does not run in CI**.

The engineering substance grades around a **B−**; the assurance *claims* grade around a **C−**. Closing that gap — partly by building the verification the docs already promise, partly by relabeling what can't be — is the central task of going from prototype to high-assurance. No agent found a `critical` defect, but the aggregate is **0 critical / 23 high / 40 medium / 23 low**, and several "high"s are real safety gaps (unbounded LSP allocation, no sanitizer/native-fuzz coverage of generated decoders, unenforced primitive bit-widths).

Claim audit tally across the review: **28 holds · 32 partial · 5 overstated · 2 false · 9 unverifiable.**

---

## 2. Efficacy Against Stated Design Goals

| # | Stated goal | Verdict | Grade |
|---|-------------|---------|------:|
| G1 | "Shared semantics, multiple syntaxes" | **Partial** — shared *planning*, per-backend *rendering* | C+ |
| G2 | LLVM/MLIR as real infrastructure | **Holds** — genuinely operational | A− |
| G3 | Contract boundaries / drift detection | **Overstated** — presence/identity guard, not drift detection | C |
| G4 | Backend parity / convergence = 100 | **Overstated → addressed (2026-07-03)** — parity/malformed/determinism now behavioral (executed pass/fail); convergence relabeled as a lint | C−→B |
| G5 | Malformed safety + determinism + release-blocking gates | **Partial → improved (2026-07-03)** — real read-path safety; gates now behavioral; big-endian present (not "absent") | C |
| G6 | Zero-overhead proof / verifier-first / fallback-free | **Overstated → partly addressed (2026-07-03)** — pass renamed `dsdl-annotate-aliasability` (drops "proof"); verifier-first/fallback-free still post-hoc/lint | C− |
| G7 | DSDL v1.0 spec conformance | **Partial** — grammar strong; primitive widths unenforced; parity narrow | C+ |
| G8 | Reproducible/deterministic builds | **Partial** — good presets; catalog & nondeterminism unguarded; CI uncommitted | B− |

### G1 — "Shared semantics, multiple syntaxes" → **Partial (shared planning, per-backend rendering)**
This is the load-bearing claim, and the truth is in the middle. A **real, substantial shared layer exists**: `lib/CodeGen/MlirLoweredFacts.cpp`, `lib/CodeGen/RuntimeLoweredPlan.cpp`, `LoweredRenderIR`, `NativeHelperContract`/`HelperSymbolResolver`, and one traversal (`lib/CodeGen/NativeEmitterTraversal.cpp`) drive field ordering, union dispatch, and helper-binding requirements uniformly. The C backend genuinely delegates to MLIR (`convert-dsdl-to-emitc` + EmitC), reimplementing nothing.

But the actual **control-flow emission is hand-written per backend.** `emitSerializeUnion` is independently coded in `lib/CodeGen/RustEmitter.cpp:559` and `lib/CodeGen/GoEmitter.cpp:585` — same intended behaviour, six separate hand-written renderings. A bug like "mask-before-validate vs validate-before-mask" in one backend would not be caught by the convergence machinery. So G1 is *aspirationally true and structurally partial*: the semantics are **planned once and rendered six times**, with cross-language agreement enforced by tests rather than by construction.

> **Update 2026-07-12 — both halves of this critique are now addressed for the union
> prologue.** The named failure mode ("mask-before-validate in one backend") is caught two
> independent ways: the **emit-order verifier** (behavioral trace comparison per (type,
> direction) against the Dafny-proven ordering class, in ctest/CI, with an end-to-end
> mutation negative control) and the **shared render template**
> (`include/llvmdsdl/CodeGen/EmitStep.h`): all five string emitters now render the union
> serialize/deserialize prologue from one canonical step list, so the order is correct *by
> construction*, with per-backend spelling classes carrying only surface idiom. And the
> same holds recursively for field bodies on the native backends (P2 step 2d, same day):
> scalar/array/composite rendering — including array-element and composite nesting — is
> driven by a shared recursive step tree, and TS/Python render through the same tree via
> the shared scripted operation plan — all five backends' spellings carry zero sequencing.
> See [docs/reference/codegen/emit-order.md](../reference/codegen/emit-order.md).

### G2 — MLIR as real infrastructure → **Holds**
This is the project's strongest claim and it is **true**. There is a proper ODS dialect (`include/llvmdsdl/IR/DSDLOps.td`, `DSDLTypes.td`, `DSDLAttrs.td`), ops with **real verifiers** (`SerializationPlanOp::verify()`, `IOOp::verify()` reject malformed union/array/cast metadata), a working pass pipeline, and a genuine EmitC lowering path producing real C. MLIR is operational infrastructure here, not scaffolding. (Minor: `dsdl.field`/`dsdl.constant` ops appear to be dead — defined but unconsumed — and should be removed or documented.)

### G3 — Contract boundaries / drift detection → **Overstated**
The contract mechanism is real and enforced at the consumer (codegen aborts on a missing/unsupported contract, with negative tests). **But it is not drift detection.** Producer stamp and consumer check both read the *same* constant `kLoweredSerDesContractMajor = 2` (`include/llvmdsdl/Transforms/LoweredSerDesContract.h:28`); within a build they cannot disagree. `lib/Transforms/LoweredSerDesContractValidation.cpp:46` checks version-equality and producer-string-equality. So it detects *"the lowering pass didn't run / raw IR was fed to a backend"* — a useful guard — but the docs' "detects producer/consumer drift early" implies semantic-compatibility checking that doesn't exist (no field-level compatibility rules, no payload divergence detection).

### G4 — Convergence / parity = 100 → **Overstated (the number measures markers, not behaviour)**
Verified in the source directly. `tools/convergence/convergence_report.py:180-282` computes the "14/14 shared" score by **`re.search`-ing each emitter's `.cpp` for call-string markers** like `collectLoweredFactsFromMlir(`, `renderSectionHelperBindings(`, `unionTagValidate`. A backend scores 100 by *mentioning* the shared helpers; it would still score 100 after weakening a validation step, as long as the marker strings remain. The same pattern holds for the **parity** scorecard (`tools/convergence/parity_matrix_report.py`: a cell is "covered" if a `ctest -N` *test name* matches a regex — it never runs the harness) and the **malformed** scorecard (`tools/convergence/malformed_contract_matrix_report.py:237`: same `ctest -N` name-presence).

Real behavioral testing *does* exist and is good — e.g. C↔Go generated, compiled, CGO-linked, round-tripped over 128 random + 265 directed cases with hard-fail on byte mismatch. The problem is purely that the **published "100" scores certify label presence, not the behaviour the docs imply.** They should be relabeled as infrastructure-consistency lints.

### G5 — Malformed safety + determinism + release-blocking gates → **Partial**
Genuinely good: the generated C **read path is bounds-safe** — it inherits the Nunavut/libcanard `copy_bits` primitive that clamps each read window to the buffer via `saturate_fragment_bits`/`choose_min` (`runtime/dsdl_runtime.h:98+`), and variable-array decode validates the length prefix *before* the element loop (no OOB writes from inflated counts).

Weak where it matters most — ~~**(a)** there is **no ASan/UBSan/MSan anywhere**~~ and ~~**(b)** only the *Python* runtime … is fuzzed~~ **(both addressed 2026-07-03: the `ci-asan` preset + `sanitizers` CI lane run ASan/UBSan over the generated C/C++/Go decoders and a coverage-guided libFuzzer lane over the native C deserializers on the real corpus — see P0)**; **(c)** ~~the "release-blocking malformed gate" is the name-presence metric above~~ **(fixed 2026-07-03: the malformed/parity/determinism gates now consume executed ctest pass/fail — behavioral, not name-presence)**; **(d)** the release `copy_bits` path uses `assert()` guards that vanish under `NDEBUG`. For an avionics-adjacent decoder of untrusted bytes, this is the single most important gap.

### G6 — Zero-overhead proof / verifier-first / fallback-free → **Overstated**
All three were read directly:

- **`dsdl-annotate-aliasability`** (renamed 2026-07-03 from `dsdl-prove-zero-overhead`; `lib/Transforms/Passes.cpp`) now matches its honest description — "annotate plans with *conservative* aliasability facts." It stamps `zoh_alias_eligible` on fixed-size/sealed/byte-aligned layouts; that flag flows out only as a generated **boolean constant** (`ZOH_ALIAS_ELIGIBLE = true/false`) and **does not switch the serializer to a zero-copy path**. It proves nothing about emitted-code overhead. (It *is* well unit-tested as an annotator, incl. a negative case.) *(The emitted `ZOH_ALIAS_ELIGIBLE`/`zoh_alias_*` surface was deliberately left unrenamed — it is a generated-API and doesn't itself claim a proof.)*
- **"verifier-first"** is **post-hoc**: invariants are validated on already-lowered IR, not enforced during lowering (`lib/Lowering/LowerToMLIR.cpp` adds no MLIR verifiers/constraints).
- **"fallback-free"** is scored by grepping cmake gate files for regexes.

### G7 — DSDL v1.0 conformance → **Partial**
Strong: the lexer/parser went through **6 documented rounds of grammar conformance** and reserved-identifier enforcement; all six directives (`@union/@sealed/@extent/@assert/@print/@deprecated`) are parsed and semantically checked; **delimited (non-sealed) bit-length sets are modeled correctly** (32-bit delimiter header + 0..extent), matching pydsdl/Nunavut.

Real conformance bug found and verified live ~~**primitive bit-width constraints are not enforced.** `uint100` and `float8` pass parse + semantic analysis and emit structurally-valid MLIR~~ **(fixed 2026-07-10:** the frontend parser and the `dsdl.io` verifier now reject out-of-range primitive widths — int/uint [1,64], float {16,32,64}, void [1,64] — with pydsdl-style diagnostics; see P0). *(Originally: `lib/Frontend/Parser.cpp:725` only checked uint32 fit; no range check in `lib/Semantics/Analyzer.cpp` or the scalar IR verifier.)* The reference compiler rejects these with diagnostics. And the **differential parity vs Nunavut covers exactly 5 files** (`test/integration/RunDifferentialParity.cmake:99`), **disables byte comparison for the union and float cases**, and **is skipped in CI** (the workflow never provisions `nunavut`/`pydsdl`).

### G8 — Reproducible builds → **Partial**
Good preset/workflow discipline and depfile support. But: the **545 KB embedded UAVCAN MLIR catalog** (`lib/CodeGen/UavcanEmbeddedMlir.inc`) ships a declared SHA-256 that is **never validated at runtime** and is **regenerated by a standalone script CMake never invokes** — so a stale or corrupt catalog ships silently. `unordered_map`/`unordered_set` appear in 10 codegen files (iteration-order determinism risk, only partly covered by determinism tests). And **CI itself is uncommitted** (`ci.yml`, `coverage.yml`, `.github/actions/` are untracked), so the "release-blocking" lanes aren't yet enforced by the repo.

---

## 3. Subsystem Scorecard (0 = prototype, 10 = high-assurance-ready)

| Subsystem | Score | One-line assessment |
|-----------|:----:|---------------------|
| Frontend (lexer/parser/discovery) | **8** | Hardened: fuzzed, crash-fixed, grammar-conformant. Add recursion/element caps. |
| Codegen Rust/Go/TS/Python emitters | **8** | High-quality, idiomatic output; ~200–500 LOC duplicated control-flow. |
| IR dialect + lowering | **7.5** | Real ODS dialect + verifiers; dead ops; lowering lacks proactive verifiers. |
| Semantics | **7** | Solid BitLengthSet algebra; **unchecked `Rational` int64 overflow**, unbounded `repeatRange` expansion. |
| Runtime (multi-language) | **7** | Read-path bounds-safe; **empty semantic-wrapper allowlist**; no isolated cross-language primitive tests. |
| Codegen C/C++/Object | **6.5** | Clean C-via-EmitC; object backend exec is shell-safe; `targetTriple` input under-validated. |
| Transforms | **6** | Real contract enforcement; zero-overhead/endianness passes renamed/redescribed (2026-07-03); big-endian **implemented** — wire is LE, `serialize_`/`deserialize_` host-agnostic, only the zero-copy view fast-path is disabled on BE. |
| Codegen shared layer | **6** | Genuine shared planning; semantics still re-rendered per backend. |
| LSP (`dsdld`) | **6** | Reuses compiler core (good); ~~unbounded `Content-Length` allocation (OOM DoS)~~ **capped + overflow-safe (2026-07-10)**; ~~DocumentStore thread-safety still open~~ **verified thread-safe (2026-07-15): every method locks `mutex_` and `lookup` returns a snapshot copy, so no reference escapes to a concurrent scheduler-worker request.** |
| Tools / CLI | **6** | Good arg/exit discipline; embedded-catalog freshness & integrity ungated. |
| Build / CI / test infra | **6** | Strong test culture; **gates are name-presence metrics**; silent toolchain skips; CI uncommitted. |
| **Headline-claim integrity** | **5** | The dominant production risk: docs promise proofs the code doesn't deliver. |

---

## 4. Top Recommendations (by leverage)

**Highest leverage — make the claims true or relabel them:**

1. **Re-found the three scorecards on behaviour, not markers.** ✅ **Done (2026-07-03) for parity/malformed/determinism** — they consume `ctest` **pass/fail** (JUnit) via `tools/convergence/ctest_results.py`; a cell is covered only if a matching test ran and passed. Convergence relabeled as an **infrastructure-consistency lint** (`docs/development/convergence-scorecard.md`) rather than made behavioral (it is inherently a marker check). Deriving convergence from generated-output/AST equivalence remains a worthwhile P1 deepening.
2. ✅ **Done (2026-07-03).** Renamed `dsdl-prove-zero-overhead` → `dsdl-annotate-aliasability` and dropped "proof" language; documented `dsdl-legalize-endianness` as validation-only (no byte reordering). ~~mark `--target-endianness big` EXPERIMENTAL/unsupported until byte-swap logic exists~~ — **withdrawn as overstated:** DSDL wire is always little-endian, so there is no byte-swap to implement; `serialize_`/`deserialize_` are host-endianness-agnostic and byte-parity-tested against little-endian in the `-l obj` smoke test. Only the zero-copy *view* fast-path is disabled on BE (returns an error), which is correct, not missing.
3. **Build the verification the docs already promise:** ✅ **Nunavut differential parity now runs in CI (2026-07-10)** — provisioned + loudly required; byte comparison always-on (non-float byte-exact, float byte-exact except NaN payloads); coverage broadened 6 → 10 cases incl. a byte-exact non-float union, fixed+variable arrays, nested composites, and a narrow scalar. **Reframed and closed (2026-07-12):** Nunavut is a *pinned peer implementation used for corroboration*, not the oracle — the Cyphal Specification is the truth and `spec/dafny/CyphalSerdes.dfy` is the machine-checked oracle. Further coverage expansion is retired by decision; see the P0 entry for the authority hierarchy and rationale.

**Safety / high-assurance:**

4. ✅ **Done (2026-07-03).** Added the `sanitizers` CI lane (linux/toolshed, Clang): ASan+UBSan over the generated native C/C++/Go decoders (via the parity harnesses recompiled instrumented) and a coverage-guided **libFuzzer lane over the generated C deserializers** on the real UAVCAN corpus, covering the nested-delimited / unions-of-composites / variable-array shapes. See the P0 entry below for the components. *(Remaining P1 deepening: expand the fuzzed type set beyond the curated 7 and enable byte-for-byte serialize re-check assertions inside the fuzz round-trip.)* ✅ **Extended to every runtime (2026-07-12): decoder fuzzing now spans all five languages.** Each memory-safe runtime gets a dedicated decoder-fuzz lane matched to its failure class — **Go** (`llvmdsdl-go-decoder-fuzz`, Go-native `go test -fuzz` over the adversarial UAVCAN set; a slice-bounds panic fails it; seed replay in CI, `LLVMDSDL_GO_FUZZTIME` for the deep run), **Rust** (`llvmdsdl-rust-decoder-fuzz`, deterministic byte stream through each `deserialize` under `catch_unwind`; a panic fails it), and **TS** (`llvmdsdl-ts-decoder-fuzz`, tsc+node over a compact adversarial fixture set; a `RangeError`/`TypeError` escaping `deserialize`, or a hang caught by the harness timeout, fails it) — alongside the existing C libFuzzer lane and the Python malformed-decode-fuzz. All accept-then-round-trip through `serialize`. Result: arbitrary wire bytes into **any** generated decoder produce a decoded object or a clean rejection, never a panic / uncaught fault / hang — verified at 8M (Go), 300k (Rust), 100k (TS) executions with zero faults. This closes the G5 "only the Python runtime is fuzzed" gap.
5. ✅ **Done (2026-07-10).** Primitive bit-length constraints are now enforced in the frontend parser *and* the `dsdl.io` IR verifier, with per-kind diagnostics. Per the Cyphal Specification these are **signed int [2,64]** (not 1 — `int1` is invalid), **unsigned int [1,64]**, **float ∈ {16,32,64}**, **void [1,64]**. See the P0 entry below. *(This corrects the earlier "int/uint 1..64" shorthand — signed and unsigned have different minimums.)*
6. **Bound the LSP:** ✅ **`Content-Length` cap done (2026-07-10)** — bounded + overflow-safe before allocation (`lib/LSP/JsonRpcIO.cpp`; see P0). Remaining: make `DocumentStore` access thread-safe (tracked under P1).
7. **Harden semantics:** checked/`__int128` `Rational` multiply; bound `BitLengthSet` expansion against adversarial `repeatRange`; cap array capacity.

**Integrity / reproducibility:**

8. **Gate the embedded catalog:** validate its SHA-256 at runtime; wire generation + `--check` freshness into CMake/CI so a stale submodule fails the build.
9. **Commit CI** and fix gate ordering (`if: always()` lets failures slip); make toolchain-missing test skips **loud** (emit a coverage manifest) so local green ≠ false confidence.
10. ✅ **Done (2026-07-11).** `semantic_wrapper_allowlist.json` is **justified-empty** (rationale documented in-file; the validator only tracks hand-written, non-generated above-primitive wrappers, of which there are none, and the release-blocking allowlist lane passes). Added the **isolated** cross-language primitive equivalence harness (`llvmdsdl-primitive-equivalence`) over **C/Rust/Go/Python/TS**, asserting each primitive direction independently (float16 pack/unpack, sign-extend, unsigned read, `copy_bits`) so paired bugs can't mask each other — which immediately **caught and fixed a real Go+Rust `float16_pack` bug**. See the P1 entry.

---

## 5. Production-Readiness Report Card → work to reach high-assurance public release

**Current standing: an advanced prototype (overall ≈ C+/B−).** Strong bones; oversold guarantees; a handful of real safety gaps. The work below is the prototype→high-assurance path, in priority order.

### P0 — Release-blocking (must close before any "high-assurance" claim)

- [x] **Truthful assurance docs.** *(Done 2026-07-03.)* Convergence relabeled as an infrastructure-consistency lint; parity/malformed carry explicit structural-vs-behavioral mode banners; `dsdl-prove-zero-overhead` → `dsdl-annotate-aliasability` (drops "proof"); `dsdl-legalize-endianness` documented validation-only; big-endian docs corrected (`docs/reference/codegen/object.md`). Big-endian **not** marked unsupported — that premise was overstated (big-endian is implemented; see the 2026-07-03 update note).
- [x] **Behavioral gates.** *(Done 2026-07-03.)* Parity/malformed/determinism scorecards consume executed ctest pass/fail via JUnit (`tools/convergence/ctest_results.py`); a cell is `covered` only if a matching test ran and passed (fail/skip/absent ⇒ uncovered). Gates hard-fail on regression (already did) and now on behavioral coverage loss. CI feeds the suite's JUnit into `release-blocking-report-gates` via the `LLVMDSDL_REPORT_GATE_JUNIT` cache var; missing results fail loudly (no silent "no data = pass"). Red-team verified: flipping one parity test to fail breaks the gate. *(Remaining nuance: the in-suite ctest coverage tests still run structurally as a fast pre-check; the authoritative behavioral gate is the post-suite target.)*
- [x] **Sanitizers + native decoder fuzzing in CI.** *(Done 2026-07-03.)* New `ci-asan`
  preset + `sanitizers` CI job (linux/toolshed, Clang-forced): ASan/UBSan over the
  generated **C and C++** decoders via the existing parity harness recompiled
  instrumented (`RunCppCParity.cmake` gains a `SANITIZE` knob →
  `llvmdsdl-uavcan-cpp-c-parity-sanitized`), and over the **Go** harness's generated-C
  side (`RunCGoParity.cmake`, linux-only variant; Go-native decoders are memory-safe
  by construction and already panic-fail the parity harness). New **coverage-guided
  libFuzzer lane** (`test/integration/NativeDecoderFuzz.c` + `RunNativeDecoderFuzz.cmake`
  → `llvmdsdl-native-decoder-fuzz`) feeds arbitrary bytes into the generated
  `deserialize_` entrypoints for the adversarial shapes (union `Frame`, nested-delimited
  `port.List`, variable-array `ExecuteCommand`, narrow scalars) under ASan+UBSan, with
  auto-emitted valid seeds + a committed regression corpus
  (`test/fuzz/corpus/native_decoder/`). Bounded `-runs` on PRs, deep run on the weekly
  cron; crash reproducers upload as CI artifacts. Degrades loudly to an ASan/UBSan
  corpus replay when a toolchain lacks compiler-rt libFuzzer (never a silent no-op).
  All builds use the Debug config so `NDEBUG` is absent and the runtime `copy_bits`
  asserts still fire. *(Verified locally sans-ASan: harness compiles in all 3 modes,
  200k coverage-guided runs clean, 7 valid seeds emitted; the ASan runtime itself was
  unrunnable only on the macOS Apple-Silicon dev box — a known shadow-memory startup
  hang — so the lane is intentionally Linux-only.)*
- [x] **Reference-parity in CI**, byte-exact incl. unions/floats, broad type coverage.
  ✅ **Closed (2026-07-12) — reframed as corroboration, expansion retired by decision.**
  **The authority hierarchy is now explicit:** the **Cyphal Specification is the truth**;
  **`spec/dafny/CyphalSerdes.dfy` is the machine-checked oracle** (op ordering, round-trip,
  read-path bounds safety — re-verified in CI); enforcement is spec-derived — the emit-order
  verifier (all 5 string backends vs the proven ordering class, full corpus), the
  spec-derived primitive golden vectors (`test/integration/primitive_vectors.txt`, absolute
  wire bytes at the primitive level, all 5 runtimes), cross-backend byte parity
  (C↔{Cpp,Rust,Go,TS} + Python), and the sanitizer/fuzz lanes. **Nunavut is a pinned peer
  implementation, not a reference**: agreement is corroboration; a mismatch is an
  *investigation adjudicated by the specification* and is as likely to be a Nunavut defect
  as ours. **The 10-case lane is retained, pinned, and blocking** — with Nunavut pinned to
  exact SHAs it functions as a regression tripwire (a newly appearing mismatch implicates
  our change first), and the 10 cases already cover every wire-shape class: byte-exact
  non-float union, float union, fixed + variable arrays, nested composites, delimited
  types, narrow non-byte-aligned scalars, floats at all widths. **The retired remainder**
  (`reg`/UDRAL namespace, `node.port.List`) would have added *instances* of already-covered
  shapes, not new shapes — instance-level correctness across the whole corpus is enforced by
  shape-generic machinery (single-source step-tree sequencing + the verifier + cross-backend
  parity), so expansion would have increased exposure to Nunavut defects without adding
  spec-grounded evidence. *(Honest residual: absolute byte layout above the primitive level
  rests on the primitive vectors + the 10 corroboration cases + single-source layout
  planning. If more absolute-layout confidence is ever wanted, the spec-consistent
  instrument is composite golden wire vectors hand-derived from the specification — not
  more Nunavut coverage.)*
  *(Pre-reframe history below.)*
  *(Runs in CI + byte-exact for all non-float and finite-float cases — 2026-07-10.)*
  **(a) Now runs in CI, non-silently.** The `linux` job provisions pinned
  nunavut+pydsdl checkouts (`.github/workflows/ci.yml`; consumed as source trees
  via `PYTHONPATH`, no pip) and configures with
  `-DLLVMDSDL_REQUIRE_DIFFERENTIAL_PARITY=ON`, so a missing reference compiler is
  a **hard configure error**, not a silent skip (the repo paths are overridable
  cache vars in `test/integration/CMakeLists.txt`). **(b) Byte comparison is now
  always on** (removed the opt-in `--strict-float-byte-parity` flag): all
  non-float types are byte-exact, and **every float-carrying type is byte-exact
  too** — including `Real32` and the `register.Value` union — after the C float
  codegen fix (2026-07-10). The scalar-float normalization helper is now
  **width-matched** (f32 for 16/32-bit fields, f64 for 64-bit) instead of always
  f64, so the generated C keeps a float in its native width end-to-end rather
  than promoting to `double` and narrowing back; that round-trip was
  canonicalizing signaling-NaN mantissa payloads and was the *sole* source of
  divergence from the reference. Verified byte-exact clean to **1,000,000** random
  iterations across all 10 cases. *(C/EmitC fix:
  `lib/Transforms/Passes.cpp` helper type + `lib/Transforms/ConvertDSDLToEmitC.cpp`
  casts/decl. The Cpp/Rust/Go emitters were width-matched the same day
  (`lib/CodeGen/HelperBindingRender.cpp` helper + the serialize/deserialize callers
  in `CppEmitter.cpp`/`RustEmitter.cpp`/`GoEmitter.cpp`), so all four native
  backends now keep floats native end-to-end and no longer canonicalize NaN via a
  double round-trip. TS/Python are inherently double-typed and cannot preserve
  float32 NaN payloads.)* **(d) Coverage broadened 6 → 10
  cases (2026-07-10)** across new wire shapes, all byte-exact and verified clean
  to 300k iterations: `node.port.SubjectIDList.1.0` (a **byte-exact non-float
  tagged union** — sparse list / bool[8192] bitset / total, the union coverage
  the float-variant `register.Value` can't provide),
  `pnp.NodeIDAllocationData.2.0` (fixed `byte[16]` + variable-length optional),
  `diagnostic.Record.1.1` (nested composite timestamp + `uint8[<=255]`), and
  `time.SynchronizedTimestamp.1.0` (narrow non-byte-aligned `uint56`); all 10 are
  byte-exact. **Remaining:** extend into the `reg`/UDRAL namespace and
  `node.port.List.1.0` (~8.5 KB, needs the harness I/O buffers enlarged). *(The
  Cpp/Rust/Go float helpers were width-matched for cross-backend consistency on
  2026-07-10 — see P2.)*
- [x] **Spec-conformance fix:** reject out-of-range primitive widths at frontend + IR verifier.
  *(Done 2026-07-10.)* The frontend now enforces the Cyphal Specification
  primitive bit-length ranges (from the "Serializable types" section) in
  `lib/Frontend/Parser.cpp` with per-kind diagnostics, so `int1`, `uint100`,
  `float8`, `int128`, and `void100` are rejected instead of lowering to
  non-conformant MLIR. **The spec gives signed and unsigned integers different
  minimums** — signed **[2, 64]** ("ranging from 2 to 64, inclusive"; the
  single-bit case is `bool`), unsigned **[1, 64]** — plus float ∈ **{16, 32, 64}**
  and void **[1, 64]**. (The "int/uint 1..64" shorthand in rec 5 / G7 below was
  imprecise; the spec text and its integer-type table are the authority, and
  `int1` matches the lexical name pattern `int[1-9]\d*` but is out of range.)
  Diagnostics read e.g. `invalid signed integer bit length 1; must be in the
  range [2, 64]`. As defense-in-depth, `IOOp::verify()` (`lib/IR/DSDLOps.cpp`)
  re-checks scalar `bit_length` against the same per-kind ranges (void also
  admits a degenerate 0-bit padding the lowering synthesizes and later drops),
  so no downstream pass or hand-authored IR can smuggle an out-of-range scalar
  into codegen. Covered by new negative+boundary cases in
  `test/unit/ParserTests.cpp` and the
  `test/lit/dsdl-io-invalid-scalar-bit-length.mlir` /
  `dsdl-io-invalid-signed-bit-length.mlir` verifier tests. *(Nuance: zero-width
  forms `uint0`/`int0`/`float0`/`void0` are already rejected one level up by the
  grammar's `[1-9]` leading-digit rule, so they fail with a type-resolution
  diagnostic rather than the bit-length message.)*
- [x] **Memory-safety hardening:** LSP allocation cap; ~~remove `assert()`-only guards from the release `copy_bits` path~~.
  *(Done 2026-07-10.)* **LSP allocation cap:** `JsonRpcStdioTransport` now bounds
  the framed payload — a `Content-Length` above `kDefaultMaxContentLength` (64 MiB,
  constructor-overridable) is rejected with `Content-Length exceeds maximum`
  *before* the payload buffer is allocated, and the header parser saturates
  instead of wrapping so a giant digit string can no longer overflow `size_t`
  into a small valid-looking length (`lib/LSP/JsonRpcIO.cpp`). Covered by new
  cases in `test/unit/LspJsonRpcFuzzTests.cpp` (oversized, overflowing, and
  at-cap-valid). **`copy_bits` asserts — premise withdrawn as overstated:** the
  release read/write paths are bounds-safe *by construction*, not via asserts.
  Every generated deserialize helper calls `saturate_fragment_bits` to clamp the
  read window to the buffer *before* `copy_bits` (`runtime/dsdl_runtime.h`
  get_bits/get_uxx), and every serialize helper checks buffer size and returns
  `-SERIALIZATION_BUFFER_TOO_SMALL` first; the `assert()`s in `copy_bits` are
  API-contract / loop-invariant checks (non-null, non-overlap, `size<=8`) that
  are *not* the memory-safety mechanism, so their absence under `NDEBUG` cannot
  cause an OOB access. They are correctly kept (zero release cost) and *do* fire
  in the ASan/UBSan+fuzz lane, which builds Debug precisely so they stay live.

### P1 — Required for a credible 1.0

- [x] Semantics overflow/DoS hardening (`Rational`, `BitLengthSet`, capacity).
  ✅ **Done (2026-07-11).** `BitLengthSet` was already overflow-hardened (`__builtin_*_overflow`
  with saturation, defects BLS-D1…D16). This pass closes the other two:
  **`Rational`** (`lib/Support/Rational.cpp`) now evaluates `+ - * /` in 128-bit intermediates and
  **poisons** (sets a sticky `overflowed()` flag, clamping to 0) when the reduced result leaves
  64-bit range instead of invoking signed-overflow UB; comparisons cross-multiply in 128-bit so
  they are always exact; and `normalize()`/`gcd()` no longer negate/`llabs` `INT64_MIN`. The
  evaluator (`Evaluator.cpp`) surfaces a diagnostic on any poisoned result and special-cases
  `intPow` for bases in {−1, 0, 1} so a huge exponent can't spin the loop (a DoS), bailing as soon
  as the running product overflows for other bases; `INT64_MIN % -1` is also guarded. **Array
  capacity**: the length-prefix width is now computed as the bit-width of `capacity` rather than
  `ceilLog2(capacity + 1)`, so an adversarial `INT64_MAX` inclusive-array bound no longer overflows
  the `+ 1` (the repeat math already saturated in the hardened `BitLengthSet`). Covered by new
  `EvaluatorTests`/`AnalyzerTests` cases (overflow → diagnostic, `1 ** huge` terminates, boundary
  comparisons, adversarial capacities analyze without crashing); verified UB-free under UBSan.
- [x] Embedded-catalog integrity + freshness gating; runtime SHA-256 check.
  ✅ **Done (2026-07-11).** Freshness gating already existed — the release-blocking
  `llvmdsdl-embedded-uavcan-catalog-guard` runs `generate_embedded_uavcan_mlir.py --check`,
  regenerating the MLIR from the submodule and failing the build if the committed
  `UavcanEmbeddedMlir.inc` is stale (plus a guard selftest). This pass adds the missing
  **runtime SHA-256 check**: the generator already baked a `kEmbeddedUavcanMlirSha256` into the
  `.inc`, but nothing verified it. `loadUavcanEmbeddedCatalog` now computes `llvm::SHA256` over the
  embedded MLIR text and refuses to parse (hard error + diagnostic) on mismatch — catching binary/
  memory corruption, tampering, or a text/hash drift. Factored into a pure, testable
  `verifyEmbeddedCatalogIntegrity` (unit-tested with the shipped blob, the known empty-string
  digest, and a rejected mismatch). **Found and fixed a latent bug** doing so: the generator hashed
  `mlir_text` but the raw-string literal embedded `"\n" + mlir_text` (a leading newline), so the
  recorded hash never matched the bytes actually shipped; the generator now hashes the exact
  embedded content. Verified: unit tests, the freshness guard (regenerates byte-identically), the
  guard selftest, and the generator's own drift/roundtrip tests all pass.
- [x] LSP concurrency correctness (DocumentStore mutex; analysis snapshot atomicity).
  ✅ **Done (2026-07-11).** **DocumentStore** was the real gap: it had no synchronization and its
  `lookup()` returned a raw `const DocumentSnapshot*` into the internal map — a dangling-pointer /
  use-after-free hazard the instant a reader holds it across a concurrent `close()`/rehash. It now
  carries a `std::mutex` guarding every operation, and `lookup()` returns a value copy
  (`std::optional<DocumentSnapshot>`) so no pointer into the map can escape. Proven under
  **ThreadSanitizer**: the 8-thread stress test (new in `LspDocumentStoreTests`) is race-free with
  the mutex and TSan flags `unordered_map` rehash/read races the moment the locks are removed.
  **Analysis-snapshot atomicity already holds** and needed no change: analysis state
  (`latestAnalysisResult_`/`analysisDirty_`) is owned solely by the main message-loop thread, and the
  async Index worker receives a **versioned immutable copy** (`scheduleRebuild(snapshotVersion,
  analysis_.buildIndexShards())`, shards taken by value) rather than a reference to shared state —
  verified. *(Note: there is no live race today — request handlers dispatch inline on the main thread
  and only a cancellable-sleep test method is offloaded — so this hardens the shared store for the
  offload-to-worker path the scheduler architecture is built toward. A dedicated TSan CI lane would
  be a worthwhile follow-up; today the concurrency test runs under the normal and ASan lanes.)*
- [x] Isolated cross-language runtime-primitive equivalence tests; populate/justify the wrapper allowlist.
  ✅ **Equivalence tests done (2026-07-11).** A shared golden-vector file
  (`test/integration/primitive_vectors.txt`, 47 vectors) is run against **all five**
  runtimes — C, Rust, Go, Python, and TypeScript — by thin per-language drivers
  (`PrimitiveEquivalenceDriver.{c,rs,go,py,ts}`, wired via `RunPrimitiveEquivalence.cmake`
  → `llvmdsdl-primitive-equivalence`; TS is optional, gated on tsc/node/dsdlc). Each
  primitive **direction** is asserted on its own — `float16_pack`, `float16_unpack`,
  signed read/sign-extension (`get_i8/16/32/64`), unsigned read, and `copy_bits` at
  arbitrary bit offsets — so a bug in one direction can't be masked by its inverse.
  **This immediately caught a real bug:** both the Go and Rust `float16_pack` mis-ported
  the C algorithm's load-bearing unsigned wraparound subtraction (Go zeroed via a guard,
  Rust used `saturating_sub`), so *every finite float16 value serialized to garbage*
  (`1.0 → 0x0000`). It was masked because the Go parity harness set `requireByteParity:
  false` on all 24 float-carrying cases. Fixed both runtimes (`wrapping_sub` / unconditional
  wrapping subtraction), and flipped all 24 Go float cases to `requireByteParity: true`
  (they now agree byte-for-byte with C at 128 random iterations). The double-typed drivers
  (Python, TS) run the same vectors and explicitly **report** the small, principled skips
  they cannot represent at the raw-primitive level (Python: float16 overflow, which its
  primitive raises on while saturation happens one layer up; TS: float16-unpack NaN results,
  which a JS number canonicalizes) — never silent, and `processed + skipped` must still
  cover every vector. ✅ **Wrapper allowlist justified (2026-07-11):**
  `runtime/semantic_wrapper_allowlist.json` carries a `justification` documenting why it is
  intentionally empty (all Rust semantic wrappers are template-generated and excluded by the
  validator; no backend ships a hand-written above-primitive wrapper), and the
  release-blocking `llvmdsdl-runtime-semantic-wrapper-allowlist` lane passes.
- [x] Determinism gates that actually perturb (`PYTHONHASHSEED`, locale/TZ, two toolchains) + audit `unordered_*` iteration in emitters.
  ✅ **Audit + env-perturbation done (2026-07-11).** **Emitter audit came up clean:** the CodeGen
  layer uses no `llvm::DenseMap`/`DenseSet`/`SmallPtrSet` (whose iteration is pointer/insertion
  ordered), every `std::unordered_map`/`unordered_set` is a keyed *lookup/membership* structure that
  is never iterated to produce output, there is no locale- or time-dependent formatting, and the
  emitters already `std::sort`/`llvm::sort` (8 sites) wherever emission order is derived from a set.
  So the generated text is already iteration-order-independent. **Gates now actually perturb:** the
  six `RunUavcan*Determinism.cmake` gates previously ran two concurrent generations in the *same*
  environment (catching only concurrency/address nondeterminism); they now run the two generations
  under deliberately different `LC_ALL`, `TZ`, and `PYTHONHASHSEED`, so byte-identical output proves
  environment-independence and would catch any future locale/TZ/hash-order dependence. All gates
  pass under perturbation. ✅ **Two-toolchain lane done (2026-07-12).** The distro LLVM in CI is
  libstdc++-built, so a same-host `-stdlib=libc++` build cannot link it; the lane crosses *hosts*
  instead: the existing linux job (libstdc++, x86-64) and a new `cross-stdlib` macOS job (Homebrew
  LLVM, libc++, arm64 — dsdlc-only build via the `dev-llvm-env` preset, with an `otool` assertion
  that the binary really links libc++) each generate the full UAVCAN corpus for all six backends
  and record a canonical per-file SHA-256 manifest
  (`tools/determinism/cross_stdlib_corpus_hash.py`); the `cross-stdlib-determinism` join job
  compares them byte-for-byte and fails with per-file detail. libstdc++ and libc++ implement
  different `std::hash`/bucket policies (and the hosts differ in arch and OS), so any future
  `unordered_*` iteration leak into emitted text diverges the manifests. The five string backends
  compare strictly always; the MLIR/EmitC-routed C backend compares strictly too — the macOS job
  pins its Homebrew LLVM to the toolshed's major (llvm@22, asserted in-job so a Homebrew bump
  fails loudly instead of eroding coverage), and the join job passes `--require-c` so any major
  skew that slips through is itself a hard failure, never a silent skip. Bump both sides
  together, deliberately. Depfiles
  (`*.d`) are excluded (absolute host paths by design). Verified locally: generation is run-to-run
  and build-dir-to-build-dir deterministic on the libc++ side, the comparator's corrupted-manifest
  negative control fails with file-level detail, and the llvm-skew path warns and skips only C.
- [x] Object backend: escape/validate `targetTriple` and staged paths.
  ✅ **Done (2026-07-12).** First, the reassuring part: the object backend already invokes the
  C/C++ compiler and archiver via **argv** (`llvm::sys::ExecuteAndWait`), never a shell, so there
  was no shell-injection vector (a hostile `--target-triple` can only ever be an inert `--target=`
  payload) — "escape" was moot; **validation** was the gap. Added: `--target-triple` is now checked
  against a conservative charset (hyphen-separated `[A-Za-z0-9._-]`, no leading dash, ≤128 chars) so
  whitespace/path/shell metacharacters are rejected up front with a clear diagnostic; `--obj-archive-name`
  must be a single safe filename component (no path separators or `..`), closing an archive-path
  traversal where `../../evil` would escape `--outdir`; and every derived object/archive path is
  containment-checked (`isPathWithinRoot`) to refuse writes outside the output root as
  defense-in-depth behind the input validation. New negative cases in `test/lit/cli.txt` prove the
  malicious triple and traversal archive name are rejected while a valid triple still passes.

### P2 — Maturity / maintainability

- [x] Reduce per-backend control-flow duplication (shared render template, or a verifier that the six emit orders match) — directly strengthens G1. Sequenced emit-order verifier → shared render template; the resulting contract is specified in **[docs/reference/codegen/emit-order.md](../reference/codegen/emit-order.md)** (the execution plan was retired once the work closed). ✅ **Phases 0–1 done (2026-07-12, branch `p2-emit-order-dedup`): the emit-order verifier is live.** All 5 string emitters (honest scope: C has no string emitter — it is covered by MLIR/EmitC + the C↔{Go,Rust,Cpp} parity harnesses) trace their abstract serialize/deserialize op stream per (type, direction) through a zero-cost-when-off side channel (`LLVMDSDL_EMIT_TRACE`); the comparator (`tools/convergence/emit_order_verifier.py`, three ctests incl. a checker selftest and an end-to-end trace-mutation negative control) asserts per-backend membership in the Dafny-proven safe ordering class (`spec/dafny/CyphalSerdes.dfy`, re-verified in CI) **and** cross-backend payload-aware wire-skeleton equality over union/array/float/padding/composite/service fixtures (26 segments) **plus the full UAVCAN public-regulated corpus (424 segments)** — all green, zero unmodeled divergences (accepted D2/D3/D4 differences are explicitly modeled in the comparator, D3 via an honest `BULK_COPY` op). The convergence scorecard preamble now points behavioral step-order claims at this verifier. ✅ **Phase 2 union prologue done (2026-07-12): the shared render template is live.** All five string backends render the union serialize/deserialize prologue through one shared step template (`include/llvmdsdl/CodeGen/EmitStep.h` — `buildUnionSectionSteps` is the single in-code statement of the canonical order) with per-backend `UnionSectionSpelling` classes expressing only the real divergence axes (match/switch/if-chain dispatch, Result/(rc,0)/negative-int/throw/raise error channels, mask folding). Proven behaviour-preserving: Rust/Go/C++ full-corpus generated output is **byte-identical** pre/post (rebuild-and-diff), and the TS/Python diff is exactly the deliberate D4 bookkeeping normalization (now all five backends emit the canonical `READ→MASK→STORE→VALIDATE→ADVANCE` order by construction — D4 closed; lit snapshots updated; C↔TS parity + Python runtime suites green). ✅ **2d for the native backends also done (2026-07-12): the recursion is shared.** `buildFieldEmitSteps` builds a recursive step *tree* (array nodes own their element's step subtree) from shared facts, and `renderFieldSteps` owns every cross-statement ordering decision — scalar helper-before-write, array length-group-before-loop, loop-contains-element, composite delimiter mechanics — recursively, for Rust/Go/C++, whose spellings now carry zero sequencing (D2/D3 became declared interface points: `spellFixedArrayLenCheck`, `trySpellArrayBulkFastPath`). Each backend proven full-corpus byte-identical pre/post. ✅ **TS/Python converged onto the same tree (same day)**: the shared scripted operation plan carries per-field step trees from the same builder, and both scripted emitters render through `renderFieldSteps` (`PyFieldSpelling`, `TsFieldSpelling`), proven full-corpus byte-identical. **All five string backends now derive their complete serdes-body sequencing from one shared source; adding a backend means writing only spelling classes. The P2 item is closed** (this was the G1 end-state).
- [x] Remove dead `dsdl.field`/`dsdl.constant` ops; add proactive verifiers in lowering.
  ✅ **Done (2026-07-12) — premise corrected + verifiers made proactive.** The review's
  "dead ops" premise was **wrong**: `dsdl.field`/`dsdl.constant` are *not* dead — they are
  schema-space introspection/documentation ops, emitted by `LowerToMLIR`, round-tripped
  through the embedded UAVCAN catalog (`UavcanEmbeddedCatalog.cpp` reads `dsdl.constant`),
  and asserted by `comments-propagation.txt`. Removing them would break doc propagation and
  the catalog. What *was* stale: the ODS **typed classes** were vestigial (created generically
  via `OperationState`, never via the generated builder) and the ODS **omitted attributes the
  lowering actually sets** (`c_name`, `section`). Fixed by making the ops first-class and
  verified rather than deleting them: ODS now declares the real attributes (optional `c_name`/
  `section`) with `let description`, and both ops carry `hasVerifier` +
  `FieldOp::verify()`/`ConstantOp::verify()` (non-empty `name` for non-padding fields —
  padding is anonymous by construction — plus non-empty `type_name`, and `value_text` for
  constants). **Verifiers are now proactive for every backend:** `lowerToMLIR` calls
  `mlir::verify()` on its own output under a scoped diagnostic handler, so all op verifiers
  (`serialization_plan`/`io`/`align`/`field`/`constant`) fire at lowering time — previously
  they ran only on the C path via its pass manager, so the native backends consumed unverified
  IR (the concrete G6 "verifier-first is actually post-hoc" gap). Adding the verify pass
  immediately caught a real over-strict invariant (padding fields legitimately have empty
  names), which the fix accommodates. Byte-identity preserved (generic creation retained, so
  no emitted-text change; full UAVCAN corpus byte-identical across all six backends); embedded
  catalog + `comments-propagation` still green. Negative test:
  `test/lit/dsdl-field-invalid-empty-name.mlir`. This closes the G2 "dead ops" note and the
  G6 "post-hoc verifier" critique.
- [ ] Split the largest emitters (Ts ~2.1k, Cpp ~2.0k LOC) into syntax/planning/naming modules.
- [x] LLVM-version lock + multi-version EmitC testing; LSP logging for post-mortems; document the LSP "AI" surface's data flow.
  **LSP adversarial data-flow / robustness audit done (2026-07-12) — four DoS defects
  found and fixed** in code the review had rated as done. All are unbounded-growth on
  attacker-controlled JSON-RPC input: **(1)** `Telemetry` keyed `requestCounts_` by the raw
  method string and recorded telemetry for *every* request including unknown methods, so a
  client streaming distinct method names grew the map without limit — now caps distinct keys
  and buckets overflow under `<other>`; **(2)** the AI `AiAuditLogger` retained up to 256
  records with unbounded per-record detail (serialized tool args, up to the 64 MiB frame
  cap ≈ 16 GiB) — detail now capped at 4 KiB after redaction; **(3)** `JsonRpcStdioTransport`
  read the header section with unbounded `getline` and unlimited header lines *before* the
  Content-Length cap applies — now per-line (8 KiB) + total-header (64 KiB) caps; **(4)**
  `RequestScheduler` had no bound on queued + in-flight requests — now a pending cap (4096);
  **(5)** the `dsdld` run loop terminated the whole server on *any* `readMessage` failure,
  including a well-framed message whose payload is merely invalid JSON (stream still
  synchronized) — so a single `Content-Length: 2\r\n\r\nxx` killed the server (availability
  DoS + LSP-spec violation). `readMessage` now flags recoverable failures and the loop
  replies `-32700 Parse error` and keeps serving; verified end-to-end (bad frame then
  `initialize` both handled). Regression tests added for all five. **Reviewed and found clean:** the Server request
  dispatch and param parsers (position/range/uri) are optional-based and guarded (negatives
  rejected, empty-container guards present, fixed-size array indexing); the redaction/gate
  consistency holds. ✅ **LLVM-version-lock write-up done (2026-07-15)** — `docs/reference/guarantees/supply-chain.md`
  records why the major is a semantic input to the output (MLIR/EmitC text may vary across MLIR
  majors, so the lock is what makes the reproducibility guarantee meaningful), where it is
  enforced (CI pins on both hosts; `--require-c` turns a major skew into a hard failure rather
  than silently retiring C coverage), and that the build itself does not assert it.
  ✅ **The "MLIR verify diagnostics leak to stderr" concern was investigated and does not exist**
  (2026-07-15): the sole `mlir::verify` call is wrapped in a `ScopedDiagnosticHandler` whose
  callback returns `success()`, so diagnostics are captured into the diagnostic engine and never
  reach the default (stderr) handler; the LSP's partial-model path does not verify at all. The
  stderr text seen in test output comes from negative-path tests that mutate IR deliberately.
  ✅ **LSP structured logging done (2026-07-15)** — `docs/reference/lsp/logging.md`. `dsdld` now emits one
  JSON object per line to **stderr** (stdout carries the protocol frames and must never be
  interleaved; the logger serialises writes so records from the main thread and the scheduler
  worker stay intact). This also makes an existing dead knob real: `ServerConfig::traceLevel` was
  parsed and documented as driving "server logs and telemetry" but **nothing consumed it** —
  verbosity is now gated by it, settable via `initialize` params, the `$/setTrace` notification
  (previously unhandled), or the `trace` setting. `request` records cover synchronous *and*
  scheduler-completed requests alike by hooking the single telemetry choke point, carrying
  method/latency/outcome; failures surface as `error_response` warnings. Records deliberately
  carry no document text or secrets. Replaces the ad-hoc `[dsdld][telemetry]` line that printed
  unstructured text on **every** request regardless of trace level.
  ✅ **LSP AI-surface data-flow document done (2026-07-15)** — `docs/reference/lsp/ai-data-flow.md`, traced
  from code rather than asserted. It answers the operator's real question ("does my DSDL source leave
  my machine?"): **no** — `OfflineAiProvider` is the only `AiProvider` implementation, it runs
  in-process, and there is no network code in the surface at all; `aiProvider_` has exactly one
  invocation site, which is the seam a future remote provider would have to cross. It records the
  bounds on what reaches the provider (`MaxSnippetBytes = 640` of source, 8 diagnostics, 24 symbol
  hints, plus structural facts), the closed four-entry read-only tool allow-list, the edit gate
  (`ApplyWithConfirmation` only), and retention (audit log is **in-memory only** — no filesystem or
  network persistence — redacted *before* a 4096-byte cap so truncation cannot unmask a secret,
  ringed at 256 records for a ~1 MiB bound). Honest about the limit: redaction is pattern-based
  masking of known secret shapes, not a proof of absence.
  ✅ **LLVM-version lock made authoritative + multi-version EmitC testing descoped (2026-07-17).**
  Maintainer decision: pin to LLVM 22 (23 is not yet stable). The lock is now enforced at configure
  time (`CMakeLists.txt` asserts `LLVM_VERSION_MAJOR == LLVMDSDL_REQUIRED_LLVM_MAJOR`, default 22, with
  a `-DLLVMDSDL_ALLOW_LLVM_MAJOR_MISMATCH=ON` escape hatch for evaluating a future major) rather than
  by CI alone, so an accidental build against another major fails loudly instead of silently producing
  divergent EmitC. "Multi-version EmitC testing" is explicitly **descoped**: it competes with the lock
  (the lock exists precisely because EmitC text may vary across MLIR majors), so guaranteeing
  reproducibility against one major is the strategy, not chasing stability across several. Rationale
  and the path to revisit are recorded in `docs/reference/guarantees/supply-chain.md`. **This line item is now complete.**
- [x] Security review of union-tag handling across backends; supply-chain/SBOM for release artifacts.
  ✅ **Union-tag review done (2026-07-12); SBOM done (2026-07-15).** The review was cheap because
  the prologue is now single-source (`buildUnionSectionSteps` + five spellings + the C/EmitC
  path). **One real defect found and fixed (UT-1, high — decode-time type confusion from
  untrusted bytes):** the union tag was stored in a hardcoded 8-bit field
  (`u8`/`uint8`/`std::uint8_t`/`uint8_t`) in **every native backend (C string, C/EmitC, C++,
  Rust, Go) and the object/ABI backend**, while the compiler computes a **16-bit wire tag**
  for unions with 257–65536 options (the mask helper is literally `& 65535`). Effect on a
  spec-legal >256-option union: serialize cannot represent options ≥256, and **deserialize
  truncated the 16-bit wire tag into the 8-bit store → wire tag 256 decoded as option 0**
  (type confusion), or a corrupted round-trip (the C/EmitC path dispatched on the untruncated
  value but stored a truncated `_tag_`). Fix: tag storage now tracks `resolveUnionTagBits`
  (`unsignedStorageType(tagBits)` / the EmitC `(uint16_t)` store cast); a no-op for every
  ≤256-option union, so the **full UAVCAN corpus is byte-identical** across all six backends
  and the ABI/object lanes. Behaviorally verified: a 300-option union now round-trips
  option 256 in generated C (`tag=256` preserved; previously decoded as `tag=0`). Regression
  test: `test/lit/union-wide-tag.txt` asserts the ≥16-bit tag storage in C/C++/Rust/Go.
  **Reviewed and found sound (no change):** validate-before-dispatch bounds the tag against
  the option count; the bad-tag `default` arm returns `BAD_UNION_TAG` in every backend; the
  mask width tracks the tag width; the helper-optional `->` derefs are guarded by the native
  skeleton's missing-helper fallback (union dispatch is unreachable when helpers are unbound);
  **TS** (numeric-literal discriminant) and **Python** (unbounded `int`) are inherently
  truncation-safe. **Peer cross-check (2026-07-12, pinned commits): UT-1 was ours alone.**
  pydsdl (`_composite.py`, pinned `a1506ce`) computes the tag width as
  `2 ** ceil(log2(max(8, (N-1).bit_length())))` — mathematically identical to our
  `pow2ceil(max(8, ceilLog2(count)))`, with its own `assert tag_bit_length in {8,16,32,64}`
  — so **our tag *width* was always spec-conformant** (a >256-option union is a 16-bit tag
  in both; the defect was strictly the hardcoded 8-bit *storage*, not the wire width).
  pydsdl emits no storage, so it cannot have the bug; Nunavut (pinned `37095ab`,
  `lang/c/templates/definitions.j2:124`) declares the member as
  `{{ t.tag_field_type | type_from_primitive }} _tag_;` — deriving the C type from pydsdl's
  computed width, so it already emits `uint16_t _tag_;` for a wide tag. Both peers are
  correct; the spec adjudicated against us. (No standard UAVCAN type has a >256-option union,
  which is why neither the differential-parity lane nor real-world use ever exercised it — the
  bug lived only in the tail we reached by construction.) ✅ **SBOM done (2026-07-15):** every
  build emits a CycloneDX 1.5 document (`cmake/GenerateSBOM.cmake`, `sbom` target in `ALL`,
  installed to `<datadir>/llvm-dsdl/` with the `bin` component) recording the tool version and
  exact source commit, the **LLVM/MLIR version actually linked** (not an aspiration), zstd when
  present, the first-party runtime, and the pinned submodule commits scoped `excluded` (build/test
  inputs, not shipped). The generator carries no wall-clock timestamp or random serial, so it
  regenerates byte-identically and does not undercut the reproducibility lanes. See
  `docs/reference/guarantees/supply-chain.md`.
- [x] **Float serialization: avoid the `float→double→float` round-trip.** ✅ **C/EmitC done (2026-07-10)** — the scalar-float helper is width-matched (f32 for 16/32-bit, f64 for 64-bit), so C keeps floats native end-to-end and preserves signaling-NaN payloads, giving byte-exact reference parity for all float-carrying types (`register.Value`, `Real32`) at 1M iterations. ✅ **Cpp/Rust/Go done (2026-07-10)** — the same width-match is now applied to the shared float helper (`lib/CodeGen/HelperBindingRender.cpp`: `const float`/`f32`/`float32` for 16/32-bit, `double`/`f64`/`float64` for 64-bit) and every serialize/deserialize caller (`CppEmitter.cpp`, `RustEmitter.cpp`, `GoEmitter.cpp`), so all four native backends keep floats in native width end-to-end and no longer canonicalize signaling-NaN payloads via a double round-trip. Verified against the uavcan-cpp-c-parity, uavcan-c-go-parity, uavcan-c-rust-parity, and generation suites. **Locked in by directed signaling-NaN payload regression cases** added to the cpp-c, c-rust, and c-go parity harnesses (feed the sNaN wire bytes `01 00 80 7F`, deserialize→reserialize, assert the quiet bit stays clear); a mutation reintroducing the round-trip makes them fail. **TS/Python are out of scope**: both are inherently double-typed and cannot preserve float32 NaN payloads, so full cross-language NaN byte-parity is not achievable regardless. *(Open spec question about what "the original value will be preserved" means for a NaN at `float16` width is captured in `NAN_PRESERVATION_QUESTION_FOR_MAINTAINERS.md`.)*

**Bottom line for the maintainer:** the hard part — a real MLIR pipeline, a hardened frontend, a defensible runtime, and a genuine differential-testing harness — is already built and largely sound. What stands between this and "high-assurance public release" is mostly **(a) making the verification as strong as the documentation already claims it is**, and **(b) relabeling the few claims that are inherently marketing.** That is a focused, weeks-not-years effort, and most of it is additive testing rather than rearchitecting.

---

## 6. Release Phasing (added 2026-07-12)

Everything above — P0 → P1, with P2 as maturity work — **is the alpha.** Language-target expansion is deliberately deferred past alpha so that a coherent first version reaches testers before the backend set grows, with the alpha → beta-1 boundary reserved as the sanctioned place to absorb breaking changes.

- [ ] **Alpha — limited release for initial feedback.** Scope = the current roadmap (P0 release-blockers first, then P1 for a credible cut; P2 as capacity allows). The target-language set is **frozen at the current six** — C, C++, Rust, Go, TypeScript, Python — plus their existing profiles (C++ `std`/`pmr`/`autosar`). Goal: get a good first version into alpha testers' hands and gather real usage feedback. **No new language backends in alpha.**

- [ ] **Beta 1 — add one new target from the deferred set.** After alpha, explore and prioritise the four candidates below and **(probably) pick one** to add first; the choice is driven by alpha feedback and demand, not decided now:
  - **Ada / SPARK** — safety-critical forcing function and the only shipping DO-178C-Level-A answer; intentionally breaks the C-syntax, exception, and integer-storage assumptions, so it doubles as the acceptance test for the shared-render abstraction. Cost: paid qualification path (GNAT Pro / SPARK Pro), Pascal-family emitter (largest template departure).
  - **Ferrocene** — really a `core`-only / `no_std` **profile of the existing Rust backend** compiled by a *certified* toolchain (ISO 26262 ASIL D, IEC 61508 SIL 3; DO-178C **not** yet achieved). Lowest syntax risk, highest ROI, and the one candidate with real first-party demand (no-std Rust).
  - **MicroPython** — a bignum / GC / `uctypes` **profile of the existing Python backend**; convenience and education nodes, non-safety-critical.
  - **WASM** — deployment target for edge / app-processor Cyphal nodes; reachable through the Rust backend (and, later, a TinyGo profile of Go); `i32`/`i64`-only, so it needs explicit narrowing codegen.
  - *Tenet to revisit when scoping:* pin the **execution model** (imperative, mutable in-place buffer, monotonic bit cursor) rather than "C-informed syntax," and let "could Ada slot in as a backend?" be the test of whether the shared-render / emit-order abstraction (P2) is genuinely language-neutral.

- [ ] **Beta 1 roadmap — authored after alpha feedback lands.** Not written now, by design. **Breaking changes are expected and acceptable across the alpha → beta-1 boundary** — this is the window to rework interfaces, land the shared-render / emit-order-verifier refactor (P2), and revise whatever alpha exposes, before API stability starts to matter.

==================================================================================================
Source: docs/development/release-packaging.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/release-packaging/
==================================================================================================

# Release packaging and distribution

How `dsdlc` / `dsdl-opt` / `dsdld` get from a git tag to a user's machine. This documents the
pipeline **as it is built today**; distribution channels that do not exist yet (Homebrew, an apt
repository, other platforms) are backlog and live in
[distribution-channels.md](distribution-channels.md).

**Today:** a tag pushes packages to a draft GitHub release — `.deb` for Ubuntu on amd64 and
arm64, and a self-contained tarball for macOS on Apple silicon. Each carries the LLVM 22 runtime
it needs, so nothing has to be added to the user's machine first.

---

## 1. What ships

| Component | Contents | Debian package | macOS |
|---|---|---|---|
| `bin` | `dsdlc`, `dsdl-opt`, `dsdld`, vendored LLVM runtime, SBOM, licences | `llvm-dsdl` | `bin/` + `lib/` in the tarball |
| `dev` | 8 static libraries, `include/llvmdsdl`, generated dialect headers, `Version.h` | `llvm-dsdl-dev` | included in the tarball |

`llvm-dsdl-dev` pins `llvm-dsdl (= <version>)`: the static libraries and headers are only
coherent against the exact build they shipped with, and dpkg refuses the pairing otherwise.

The generated output is self-sufficient. Each backend writes its own runtime support scaffold
into the output tree, and those scaffolds are compiled into the binary
([tools/runtime/generate_embedded_runtime.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/tools/runtime/generate_embedded_runtime.py)),
so a packaged `dsdlc` emits code that compiles on a machine which has never seen this source
tree.

---

## 2. Build environments

### Linux: Ubuntu 22.04 (jammy)

Built in [packaging/docker/Dockerfile.ubuntu-release](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/docker/Dockerfile.ubuntu-release).
22.04 is the oldest release apt.llvm.org publishes LLVM 22 for, which puts the glibc floor at
2.35 and lets one package install on 22.04, 24.04 and 26.04 alike. The image adds two third-party
apt sources because Ubuntu 22.04 ships neither: apt.llvm.org for LLVM/MLIR 22, and apt.kitware.com
for CMake ≥ 3.24 (jammy has 3.22).

**The CI toolshed image is not reused for releases.** It is Ubuntu 26.04, and a `.deb` built
there links a glibc that refuses to install on anything older — which would silently cost every
24.04 user, the largest group.

Reaching back to 22.04 cost one code change. `std::flat_set` reached libstdc++ only in GCC 15
(Ubuntu 26.04), so [include/llvmdsdl/Support/FlatSet.h](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/include/llvmdsdl/Support/FlatSet.h)
provides it instead, on every platform. Building against libc++, which does have `flat_set`, is
the obvious-looking alternative and is closed: the distro `libLLVM` links libstdc++, and putting
two C++ runtimes either side of MLIR's `std::string` boundary is an ABI hazard that yields
undefined symbols or a quietly ODR-broken binary.

### macOS: `macos-15`, Apple silicon

Homebrew LLVM at build time, vendored into the artifact. Intel macOS is not built; see the
[backlog](distribution-channels.md).

---

## 3. Vendoring the LLVM runtime

Neither Ubuntu nor a stock macOS carries LLVM 22, and a downloaded file has no dependency
resolver behind it. Without vendoring, a package installs cleanly and dies on first run with a
missing shared object, with nothing to fall back on.

`LLVMDSDL_VENDOR_LLVM` (default off — an ordinary `cmake --install` should not copy ~150 MB into
the install tree) means "self-contained" on both platforms, by platform-appropriate means:

- **Linux** — `libLLVM.so.22.1` installs to `/usr/lib/<multiarch>/llvm-dsdl/`, with CMake's
  `INSTALL_RPATH` putting `$ORIGIN/../<libdir>/llvm-dsdl` on the three tools. A private directory,
  not `${CMAKE_INSTALL_LIBDIR}`: this is our copy of someone else's library and must satisfy
  nothing but our own tools.
- **macOS** — [cmake/BundleSelfContainedTools.cmake](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/cmake/BundleSelfContainedTools.cmake)
  copies the tools and their dylibs into `bin/` + `lib/`, rewrites Mach-O install names to
  `@executable_path/../lib` and `@loader_path`, and ad-hoc codesigns. When vendoring is on, the
  install rules install that bundle rather than the raw targets.

LLVM is Apache-2.0-WITH-LLVM-exception, so redistribution is fine with attribution;
[packaging/deb/copyright](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/deb/copyright) carries the stanza covering the shipped
library.

### Dependencies are derived, never written by hand

`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` is off. `dpkg-shlibdeps` resolves every linked library against
the dpkg database, and the vendored `libLLVM` belongs to no installed package, so it either fails
or invents a wrong dependency.

The list is instead derived from the built binaries at package time by
[packaging/deb/derive_depends.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/deb/derive_depends.py): walk what the tools
*and the vendored library* link, drop what ships inside the package, map the rest through
`dpkg -S`. It runs from a CPack project-config script, because the binaries do not exist at
configure time.

The vendored library's own dependencies are the ones that bite. The current list is `libbsd0`,
`libc6`, `libedit2`, `libffi8`, `libicu70`, `libmd0`, `libstdc++6`, `libxml2`, `libz3-4`,
`libzstd1` — all from the stock Ubuntu archive, and all but two contributed by `libLLVM` rather
than by our own code.

---

## 4. Debian packaging

`.deb` generation is CPack's DEB generator driven by the existing install components
([cmake/Packaging.cmake](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/cmake/Packaging.cmake)). `CPACK_DEB_COMPONENT_INSTALL` maps
`bin`/`dev` onto the two packages.

Compression is **xz**, not CPack's default gzip: the package is dominated by a vendored library
that compresses well, and this is a file people download directly — 74 MB → 46 MB measured.

### Policy metadata

Debian keys these off the *binary package* name, so each package needs its own copy.
`CMAKE_INSTALL_DOCDIR` only covers `llvm-dsdl`; the `llvm-dsdl-dev` destination is spelled out.

- **[packaging/deb/copyright](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/deb/copyright)** — DEP-5, covering the project's MIT
  terms and the Apache-2.0-with-LLVM-exception of the shipped `libLLVM`.
- **[packaging/deb/changelog](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/deb/changelog)** — CPack has no changelog support, so
  it is gzipped (`-n`, for a byte-identical result across builds) and installed by hand. Its top
  entry restates the version; a package whose changelog disagrees with its control file is
  malformed, so configure fails on the mismatch.
- **[packaging/deb/lintian-overrides/llvm-dsdl](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/deb/lintian-overrides/llvm-dsdl)** —
  the tools ship unstripped, neither stripped nor split into `-dbgsym`. For a compiler of an
  avionics-adjacent wire format, the symbols needed to read a backtrace should already be on the
  machine that produced the core. The override carries no file hint: lintian releases disagree on
  how hints are rendered, and a hint that does not match the running version is silently inert.

Both packages are lintian-clean.

### Man pages

Generated from each tool's own `--help` by
[tools/man/generate_manpage.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/tools/man/generate_manpage.py), so the two cannot drift.
Two help dialects are parsed: the `NAME`/`SYNOPSIS` sections `dsdlc` and `dsdld` print, and LLVM's
`cl::opt` format `dsdl-opt` inherits. Anything not structurally mappable is emitted verbatim in a
preformatted block rather than guessed at. The page date comes from the changelog's release
trailer, not the clock, so rebuilds are byte-identical.

This runs each tool to document it, so it needs host-executable binaries — fine natively, but a
cross-build would have to generate the pages host-side.

---

## 5. macOS packaging

The tarball is the bundle described in §3: `bin/`, `lib/`, licences, and a manifest. It is
relocatable — extract anywhere, add `bin/` to `PATH`.

### Gatekeeper

The binaries are ad-hoc signed rather than notarized, and `spctl -a -t exec` rejects them. That
matters only for files carrying `com.apple.quarantine`, which depends entirely on how the archive
is opened:

| Path | Quarantine on extracted files | Result |
|---|:--:|---|
| `curl` + `tar -xzf` | no | runs |
| Browser download + `tar -xzf` | no | runs |
| Browser download + Finder double-click | yes | **blocked** |
| `brew install` | no — brew strips it | runs |

`tar` does not propagate quarantine; Archive Utility does. So the tarball needs no Developer ID
and no notarization, **provided the install instructions say `tar -xzf`** — which the release
notes do. Notarization is the usual answer for shipping macOS binaries and would cost a paid
certificate, `notarytool`, and secrets; it buys only the Finder row.

---

## 6. The release workflow

[.github/workflows/release.yml](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/.github/workflows/release.yml), triggered by a `v*` tag or
by `workflow_dispatch` (which defaults to a dry run that builds and verifies without publishing).

```
tag v* ──▶ stage ──▶ build   (ubuntu-22.04-arm, ubuntu-22.04) ──▶ publish
             │       macos   (macos-15)                            │
        version/tag      each: build → package → verify        draft release,
        consistency                                            checksums, attestation
```

- **stage** — derives the version from `VERSION`, fails if a tag disagrees with it, and checks the
  changelog's top entry matches. A tag that disagreed would ship binaries misreporting themselves.
- **build** / **macos** — each runs on a native runner for its architecture; CI never emulates.
  Emulation is only how a developer on one architecture cross-checks the other locally, which is
  what `smoke.py --platform` exists for. The legs are independent (`fail-fast: false`): one
  architecture's package is installable without the other.
- **publish** — downloads each artifact into its own subdirectory (every build job writes a
  `SHA256SUMS`, so merging would leave one overwriting the others), rebuilds one checksum file
  from what is actually attached, attests provenance, and creates a **draft** release.

Reference point for capacity planning: the arm64 Linux leg, including building the release
container image from scratch, completed in 5m30s on GitHub's arm64 runner against a 90-minute
timeout.

---

## 7. Verification

A package that only works where it was built is the failure mode all of this is built to catch,
and with no repository behind a downloaded file, nothing else would notice.

| Check | What it proves | Where |
|---|---|---|
| [smoke.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/verify/smoke.py) | The `.deb` installs on **pristine** Ubuntu with no apt.llvm.org, all three tools run, `libLLVM` resolves through RPATH, generated C compiles with stock `cc`, a non-C backend emits | release workflow |
| [smoke_macos.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/verify/smoke_macos.py) | Every non-system reference in every binary and dylib resolves **inside the bundle**, tools run, generated C compiles | release workflow |
| [check_deb_config.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/verify/check_deb_config.py) | Control fields, component split, version pin, lintian verdict — against real packages built in a container | ctest (`llvmdsdl-packaging-deb-config`) |
| [test_check_deb_config.py](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/packaging/verify/test_check_deb_config.py) | The verdict logic itself, against recorded output — no Docker needed | ctest (`llvmdsdl-packaging-deb-config-selftest`) |

Two design points worth keeping:

**macOS asserts linkage, not just behaviour.** There is no pristine container to install into, and
the build runner is the worst possible judge — it has Homebrew LLVM at exactly the paths a
non-relocated binary would reference, so a tarball that only works there would pass every
behavioural test.

**The verdict logic is tested without Docker.** The containerised check registers only when a
`docker` binary exists and exits 77 — which `SKIP_RETURN_CODE` turns into a ctest *skip* — when
the daemon is unreachable. The CI Linux lane runs inside a container and has no Docker of its own,
so without this it would either fail to configure or report a green test that never ran. Pass
`--require-docker` to make an unusable daemon a hard failure; the release lane should, since a
silent skip there would let an unverified package through.

---

## 8. Why not cross-compile

Building every target from one Linux runner is the obvious way to avoid a native runner per
architecture, and `zig cc` is the obvious tool. It does not work here, and the reason is worth
recording because the idea will resurface.

**This is a dependency problem, not a compiler problem.** Zig supplies a clang that emits aarch64
or Mach-O code, libc headers, and glibc version stubs. It does not supply `libLLVM` for the target
or the MLIR archives we link.

1. **No target-built LLVM/MLIR.** You would have to cross-build LLVM first — which is the cached
   toolchain in the [backlog](distribution-channels.md), at which point native is simpler
   — or scrape prebuilts into ad-hoc sysroots.
2. **C++ ABI mismatch if you scrape.** apt.llvm.org builds against libstdc++, Homebrew against
   libc++, and zig bundles its own libc++ with no libstdc++ at all. MLIR exports a great deal of
   templated C++; mixing standard libraries across that boundary yields undefined symbols or a
   quietly ODR-broken binary.
3. **TableGen must run on the build host.** [include/llvmdsdl/IR/CMakeLists.txt](https://github.com/OpenCyphal-Garage/llvm-dsdl/blob/main/include/llvmdsdl/IR/CMakeLists.txt)
   invokes `mlir_tablegen()` eight times; pointing CMake at a target-arch MLIR yields a
   `mlir-tblgen` that cannot execute on the builder.
4. **Verification requires execution anyway.** Every check in §7 runs the binary. Cross-compiling
   removes the build runner and leaves the test runner — the one that matters. On a public
   repository the native runners are free.

The intuition it comes from is sound: zig's real strength is decoupling the glibc floor from the
build host. But with vendoring, that floor is set by the prebuilt `libLLVM` we ship rather than by
our own objects, so the cure for it is owning our LLVM toolchain.

Worth revisiting if the cached toolchain lands *and* someone wants to collapse the build matrix
further: blockers 1 and 2 disappear, 3 is mechanical, and only 4 remains — capping the win at
"fewer build runners, same number of test runners".

==================================================================================================
Source: docs/development/distribution-channels.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/distribution-channels/
==================================================================================================

# Distribution channels (backlog)

Distribution channels that do not exist yet, and the decisions still open about them.

The pipeline that **does** ship today — what the `.deb` and macOS tarball contain, the build
environments, LLVM vendoring, Debian and macOS packaging, the release workflow, verification,
and why cross-compiling is closed — is documented as built in
[docs/development/release-packaging.md](release-packaging.md). A bare section reference
below (§3, §6, §8) points *there*; a reference to a section of this document says "above".

---

## 1. Homebrew

A tap (`OpenCyphal-Garage/homebrew-llvm-dsdl`) needing a PAT held as a secret here. The formula
builds from source, and CI additionally produces bottles so the common path is a binary download:
`brew install --build-bottle`, `brew bottle --json --root-url=<release asset URL>`, attach the
bottle to the release, `brew bottle --merge --write`, commit to the tap.

Bottles are keyed by macOS version, not just architecture — a bottle built on `macos-15` is
`arm64_sequoia`, and a Sonoma user silently builds from source instead. Build the newest two the
runners offer and let the rest compile. Run `brew style` and `brew audit --strict --online` in the
package job.

**The formula should vendor**, matching the `.deb`, via `depends_on "llvm@22" => :build` plus the
install-name rewriting §3 already does. `depends_on "llvm@22"` at runtime is the idiomatic answer
and the one to reach for by default, but the measured cost is lopsided: a 218 MB vendored bundle
against the 1.7 GB `llvm` keg a user would otherwise install to run a ~12 MB compiler. The usual
objection — that vendoring forecloses homebrew-core — does not bite here, because homebrew-core is
blocked by the LLVM pin below regardless, and a formula is a few dozen lines to rewrite if that
ever changes.

For reference when writing the formula: Homebrew's current `llvm` is 22.1.8, our locked major, and
`llvm@22` is an alias for it. Real versioned formulae exist for `llvm@14` through `llvm@21`, so
each major gains one as it is superseded — `depends_on "llvm@22"` should keep resolving across the
rollover. A scheduled canary asserting that `llvm@22` resolves *and* reports major 22 turns a
break into a red check rather than a user's bug report.

## 2. Upstream homebrew-core

Blocked by the **LLVM major lock**, not by packaging. homebrew-core rebuilds dependents when
`llvm` bumps, and `LLVMDSDL_REQUIRED_LLVM_MAJOR` hard-fails configure against any other major — by
design, because EmitC output varies across MLIR majors and this project pins byte-reproducibility
to one (see [supply-chain.md](../reference/guarantees/supply-chain.md)). A formula that refuses to build the day `llvm`
rolls is one homebrew-core will not carry.

| Option | Cost |
|---|---|
| Track LLVM majors promptly, bumping the lock as each lands | Ongoing maintenance tied to LLVM's cadence |
| Accept a range of majors, reproducibility guaranteed per-major | Weakens the single-major guarantee |
| Stay in our own tap | No upstream, no compromise |

The tap costs nothing and forecloses nothing. This should be decided on its own merits rather than
under a packaging deadline. (homebrew-core also has a notability bar, which is a matter of
adoption rather than engineering.)

## 3. apt repository

A static file tree on GitHub Pages from a `gh-pages` branch:

```
dists/stable/{InRelease,Release,Release.gpg}
dists/stable/main/binary-{amd64,arm64}/Packages{,.gz}
pool/main/l/llvm-dsdl/*.deb
```

Generated with `apt-ftparchive`, `InRelease` signed with a release key held in secrets. Sign from
the start — the alternative is teaching users `[trusted=yes]`. Publishing must be **additive**:
download the existing index, add the new pool entries, regenerate. Regenerating from only the
current release silently deletes every prior version.

The DEP-5 `copyright` already covers the vendored library, so nothing about the repo changes the
packaging.

## 4. Other platforms

- **Intel macOS.** Requires either an x86_64 runner or `-arch x86_64` on the arm64 runner with
  verification under Rosetta 2. The bundle is architecture-specific, so a universal binary would
  mean building both halves.
- **snap.** A natural fit — snaps bundle everything, so the vendoring question disappears. `base:
  core24`, `confinement: strict`, plugs `home` and `removable-media`.
- **Windows.** WinGet accepts a plain zip with `NestedInstallerType: portable`, and Scoop is nearly
  free on top of the same zip. The packaging is easy; the *build* is not, because there is no
  prebuilt LLVM 22 with MLIR for Windows. It is blocked on the cached-toolchain pipeline below.
- **RPM.** CPack's RPM generator plus a Fedora COPR project — the cheapest format to add, since the
  component split and vendoring are already settled.

## 5. Cached LLVM toolchain

Several constraints trace back to *whose* LLVM 22 we build against: the glibc floor is
apt.llvm.org's choice, the brew formula follows Homebrew's lifecycle, and Windows has no prebuilt
LLVM with MLIR at all. Building LLVM/MLIR 22 ourselves once per target, caching it as a GHCR image
or release artifact keyed by `llvm-rev + triple + stdlib`, and restoring it in the build job
dissolves all three. It runs when the pin changes, not per release.

This is deliberately not a prerequisite for anything shipping today. The four-stage workflow
factoring (§6) exists so the toolchain source is an implementation detail of the build job: it can
swap in later without touching the package, verify, or publish stages.

Landing it would also reopen cross-compilation, which is closed today for reasons recorded in §8:
blockers 1 and 2 disappear, 3 is mechanical, and only "verification requires execution" remains.

---

## 6. Open decisions

| # | Decision | Current answer |
|---|---|---|
| D1 | Who owns the tap and apt repo | `OpenCyphal-Garage`, matching `upstream` |
| D2 | Is Intel macOS supported | Not built; `-arch x86_64` plus Rosetta verification is the likely route if wanted |
| D3 | Does `llvm-dsdl-dev` publish | Built and verified; published to apt when the repo exists |
| D4 | Glibc floor once we build our own LLVM | Undecided — a supported-distro policy question, not a technical one |
| D5 | The LLVM major lock vs upstream homebrew-core | Undecided; see §2 above |

==================================================================================================
Source: docs/development/convergence-scorecard.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/development/convergence-scorecard/
==================================================================================================

# Shared-Infrastructure Consistency Lint

Generated by `tools/convergence/convergence_report.py`.

> **What this is.** A *static lint* that verifies each backend emitter references the shared planning/lowering helpers and gates (field-step ordering, union-tag validation, lowered-contract validation, and so on). A `shared` mark means the marker for that class is present in the emitter source: it certifies **infrastructure consistency, not runtime behavioral equivalence.** Behavioral equivalence is enforced separately: emitted *step order* by the **emit-order verifier** (`tools/convergence/emit_order_verifier.py`, ctest `llvmdsdl-emit-order-verifier`), which compares each string backend's abstract serialize/deserialize op trace per (type, direction) against the equivalence class proven safe by the Dafny oracle (`spec/dafny/CyphalSerdes.dfy`); and *wire bytes* by the parity and malformed-input gates, which consume executed test pass/fail. Read each number here as *markers present*, not as a correctness proof or a convergence guarantee.

## Summary

| Backend | Markers present | Classes shared / total |
| --- | ---: | ---: |
| `c` | `100` | `14 / 14` |
| `cpp` | `100` | `14 / 14` |
| `go` | `100` | `14 / 14` |
| `python` | `100` | `14 / 14` |
| `rust` | `100` | `14 / 14` |
| `ts` | `100` | `14 / 14` |

Project floor (minimum markers-present score across backends): `100`

## Per-Backend Classifications

### `c`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

### `cpp`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

### `go`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

### `python`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

### `rust`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

### `ts`

| Semantic class | Status |
| --- | --- |
| `Field step ordering` | `shared` |
| `Union tag mask and validation` | `shared` |
| `Scalar cast/normalize and sign extension` | `shared` |
| `Variable array prefix normalize and length validation` | `shared` |
| `Fixed array cardinality validation` | `shared` |
| `Delimited payload header validation` | `shared` |
| `Section capacity pre-check` | `shared` |
| `Alignment/padding orchestration` | `shared` |
| `Malformed-input diagnostic category text` | `shared` |
| `Lowered contract schema/version validation` | `shared` |
| `Helper-binding completeness gates` | `shared` |
| `Verifier-first invariant enforcement` | `shared` |
| `Contract-v2 wire-program usage` | `shared` |
| `Fallback-free semantic execution gates` | `shared` |

==================================================================================================
Source: docs/agents/index.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/agents/
==================================================================================================

# Agent Guide

Written for coding agents and documentation indexers rather than for people. Facts are stated flatly
and without narrative; everything here is also reachable from the human navigation.

If you are ingesting this site programmatically, start with [`/llms.txt`](../llms.txt) — a link index
of every page with a one-line summary — or [`/llms-full.txt`](../llms-full.txt), which is the entire
manual as a single document. Both are regenerated on every publish. Their format is described in
[Documentation Index](index-format.md).

## Overview

`llvm-dsdl` compiles OpenCyphal DSDL (Data Structure Description Language) definitions into
serialization code for several languages, and into compiled object code. It is built on MLIR and
LLVM: DSDL is parsed into a dedicated MLIR dialect, lowered through passes, and emitted by per-language
backends.

It is not a runtime, a transport implementation, or a Cyphal node library. It produces the types that
such a library moves.

## Tools

| Tool | Purpose |
|---|---|
| `dsdlc` | Compile DSDL; emit generated code or object files. The tool you want in almost every case. |
| `dsdl-opt` | Run passes over the `dsdl` MLIR dialect. Compiler-development tool. |
| `dsdld` | Language server (LSP) for DSDL source. |

## `dsdlc` surface

Target languages, via `--target-language` / `-l`:

`ast`, `mlir`, `c`, `cpp`, `rust`, `go`, `ts`, `python`, `obj`

Per-language selectors:

| Language | Selector | Accepted values |
|---|---|---|
| `cpp` | `--cpp-profile` | `std`, `pmr`, `both`, `autosar` |
| `rust` | `--rust-profile` | `std`, `no-std-alloc` |
| `rust` | `--rust-crate-name` | crate name |
| `go` | `--go-module` | module path |
| `ts` | `--ts-module` | module name |
| `python` | `--py-package` | package name |
| `obj` | `--target-endianness` | `little`, `big` (required for `obj`) |

A language selector passed with a different `--target-language` is an error, not a no-op.

Input and output:

- `--outdir` / `-O` — output directory
- `--lookup-dir` / `-I` — additional DSDL root, repeatable
- `--list-inputs`, `--list-outputs`, `--dry-run` / `-d`, `-MD` — planning and dependency output without
  writing generated code

`dsdlc --help` is authoritative for exact switch semantics. Prefer running it over inferring from this
page when the two could disagree.

## Reading the generated output before generating any

The [Showroom](../showroom/index.md) is a complete vendor-style namespace compiled into every language
and profile, with per-type pages carrying the wire layout and the generated code side by side. It is
the highest-density description of what this compiler actually produces, and it is generated by the
compiler itself rather than written by hand. Index it.

## Generated and authored pages

Generated at publish time, never committed, never edited by hand:

- `showroom/index.md` and `showroom/types/*` — rendered from compiler output
- `reference/guarantees/parity-matrix.md`, `reference/guarantees/malformed-input.md`,
  `reference/guarantees/determinism.md`, `development/convergence-scorecard.md` — rendered from the
  report generators under `tools/convergence/`
- `llms.txt`, `llms-full.txt`

Everything else is authored prose under `docs/` in the repository, editable via the "Edit on GitHub"
link on each page.

## Stability

- Page URLs follow the `docs/` directory layout: `docs/reference/commands/dsdlc.md` publishes at
  `/reference/commands/dsdlc/`. A path change is a page move, and there is currently no redirect layer.
- The site is unversioned and tracks `main`. It is not a record of any released version. Where a page
  states a version, that statement is the version's, not the site's.
- The manual describes the tools; the repository is the source of truth for behaviour. When a page and
  the code disagree, the code is right and the page is a bug.

## Related but different

`dsdld` has an optional, policy-gated AI surface of its own — that is a feature *of the language
server*, unrelated to this section. It is documented under
[AI Operation](../reference/lsp/ai-operation.md) and [AI Data Flow](../reference/lsp/ai-data-flow.md).
Do not conflate the two when summarizing this project.

==================================================================================================
Source: docs/agents/index-format.md
URL: https://opencyphal-garage.github.io/llvm-dsdl/agents/index-format/
==================================================================================================

# Documentation Index

Two machine-readable views of this manual are published at the site root.

| File | Contents |
|---|---|
| [`/llms.txt`](../llms.txt) | A link index: every page, grouped by section, with an absolute URL and a one-line summary. Small enough to load before deciding what to fetch. |
| [`/llms-full.txt`](../llms-full.txt) | The manual concatenated as one Markdown document, each page preceded by its source path and URL. One fetch, no crawling. |

Both follow the [llms.txt](https://llmstxt.org/) convention.

## Generation

`tools/docs/build_llms_index.py` reads the navigation in `mkdocs.yml`, resolves each entry to its
published URL, and takes the summary from the page's own first paragraph. Nothing in either file is
maintained by hand, so neither can describe a page that does not exist or miss one that does.

The generator runs as part of the documentation build, after the showroom pages and the guarantee
matrices have been generated, so the compiler's own output is included rather than skipped.

## Coverage

`llms.txt` lists every page in the navigation **plus** the [showroom](../showroom/index.md) type
gallery. Those per-type pages are deliberately absent from the human navigation — two dozen entries
in a dropdown help nobody — but they are among the most useful pages here for a machine reader, so
each is listed with its own URL.

`llms-full.txt` carries the manual only. The type gallery holds the full generated code for every
type in eight language/profile variants, which is roughly four times the size of the manual; folding
it in would make one fetch expensive for every reader who wanted the prose. Fetch the type pages you
need from the URLs in `llms.txt`.

## Guarantees on the content

- **No timestamps.** Regenerating from an unchanged tree produces byte-identical output, which is the
  same property the compiler itself is held to.
- **Absolute URLs**, rooted at the `site_url` in `mkdocs.yml`.
- **Coverage is enforced.** A page under `docs/` that appears in neither the navigation nor the
  generator's exclusion list fails the build. The index cannot silently fall behind the manual.