RIDL

One platform, four languages, one grammar. RIDL is a family of languages for modeling component-based reactive systems: a shared vocabulary layer and three description languages over it, sharing one grammar, one toolchain, and one intermediate representation (IR).

The family

The dependency lattice is typl ← {ridl, rmdl} ← rsdl: typl is the only standalone member, and rsdl is the apex that composes the others. rxdl is not a language — it is a file kind that lifts restrictions, plus spellings over ridl's interaction families (ADR-0012).

What is built

Three layers of the family have a working toolchain in this repository:

• typl — the vocabulary layer: compiler, ridl fmt, an LSP server, and a VS Code extension.
• ridl — the interface layer over it: the five interaction kinds, timing annotations, contracts, interfaces and services, a TypeScript code generator beside the Rust one, and ridl diff.
• rsdl — the architecture layer: components, the system, distributions and deployments, checked against the rsdl reference and lowered to the IR beside the package IR, and ridl diff at the system. See Describing a system.

ridl-rt is the no_std runtime library that a generated ridl package links and a runtime implements: identity, time and the envelope, samples, the payload traits, the interaction descriptors, the ports, and the contract and transport errors. It has no dependency in any feature combination. ridl-loopback implements its ports in process, and the Rust crate ridl-transport-ws serves the WebSocket binding: it carries the observe and call ports to a second process, as the providing side of a frame session on a connection the program that embeds it accepted. The TypeScript package @driftsys/ridl-transport-ws (packages/ridl-transport-ws/) is the consuming side of that binding, for Deno and the browser. No other transport is built. The three payload codecs, FlatBuffers, proto3 and podbuf, are built: the Rust backend emits a codec for the payload types of a package for each one the manifest names, and ridl build --emit podbuf writes the C header of the podbuf layout.

ridl build --emit writes Rust source, TypeScript source, a proto3 schema, a FlatBuffers schema, or the IR as JSON, with the lowered rsdl system beside it.

rxdl and rmdl are specified but not built. Their language references are complete enough to design against, but no compiler accepts them and nothing in this book describes them as usable. rmdl is parked, with no implementation scheduled; rxdl keeps only its unrestricted profile, narrowed to types, interfaces and wiring, scheduled in step 2.

There is no runtime you can run a contract over from a command in this book. Of the transport bindings, the WebSocket one is implemented, by ridl-transport-ws, which a program embeds; the delivery semantics of the others are specified and not implemented. Provider-side contract enforcement is: the generated serve evaluates a require and an ensure clause and settles the contract error, and the Rust backend's tests run that over the in-process runtime below. Nothing the compiler emits links a runtime, so none of it is reachable from a command in this book. ridl-rt (above) is the library a runtime implements, not a runtime itself — it performs no I/O and links no codec. The repository does hold one runtime, ridl-loopback: an in-process reference that carries values between a provider and a consumer in one program, with no transport, no wire format and a clock a test advances by hand. Nothing the compiler emits links it yet, so it is reached only from a program written against it by hand.

Getting started walks through what you can run today.

Where the specifications live

This book is the reader's entry point. The normative documents live in the repository:

• Specifications — docs/specification/: the normative home of the family overview, the family general form (the surface rules every language shares), the five language references, the expr-core specification (the shared grammar of require / ensure clauses), and the frame specification (what crosses a runtime boundary per interaction kind). Every one of them except the family overview and the general form is reproduced in this book's Language reference section — typl, ridl, rxdl, rmdl, rsdl, expr-core, frame.
• Work in progress — docs/wip/: the pre-ADR concept note and the authoring-skill outline.
• Decisions — docs/decisions/: the architecture decision records — ADR-0002 (module system), ADR-0004 (implementation sequencing and stack), ADR-0005 (agent enablement), ADR-0006 (walking-skeleton execution), ADR-0007 (E1 execution), ADR-0008 (E2 execution), and ADR-0009 (toolchain and gate parity).
• Technotes — docs/technotes/: informative architecture notes, which bind nothing.
• Roadmap — docs/ROADMAP.md: the forward plan — the two steps the 2026-09-12 re-scope sets, the parked blocks with the observation that reopens each, and the milestone summary. What has already shipped is in docs/archive/roadmap-landed-record.md.
• Archive — docs/archive/: superseded documents, and the plans of the epics that have landed.

Browse them on GitHub: https://github.com/driftsys/ridl/tree/main/docs.

Status

The typl and ridl references are no longer drafts; the version and status of every specification are in the family overview. The toolchain is released as binaries on GitHub and as crates on crates.io. This book describes the main branch, which can be ahead of the newest release; Getting started says how to build it from a clone.

Reading guide

The specifications are separate by design — one learnable whole per audience. Each path below is a route through the same four languages, not a different set of them. Pick the path for your role; each links to the full reference. The family overview (docs/specification/ridl-family-overview.md) is the map that ties them together.

typl, ridl and rsdl have a toolchain. A path below that ends in rxdl or rmdl ends in a specification you can design against but cannot compile — see what is built.

• Data architect — typl, end to end. It stands alone.
• Service / bus SSOT engineer — typl §1–§10, then ridl end to end.
• UX / frontend engineer — typl §1–§10, ridl's core semantics and the presentation and intent families, then rxdl (specified, not built).
• Sensor / actuator engineer — typl §1–§10, ridl's acquisition and control families and their correspondence obligations, then rxdl §5 (specified, not built).
• Control / algorithm engineer — typl §1–§10, ridl §3/§9, then rmdl (specified, not built).
• Integrator / architect — everything above at survey depth, then rsdl, with Describing a system.
• Auditor / safety assessor — the family overview's shared doctrines, then typl's keyword registry and evolution model, ridl's error strata and services, and the diagnostics table of each reference.

Writing your first .ridl file rather than reading a specification? Start with First steps, then Getting started.

For the motivation and the big picture, read the concept note (docs/wip/ridl-family-concept.md); for the shared surface rules across every profile, the general form (docs/specification/family-general-form.md). Building the toolchain? Start with the roadmap and the decision records.

First steps

This chapter takes you from nothing to a checked package and a generated Rust crate, in five steps. It states each step once and links to the chapter that owns the detail. Read Getting started next for the language itself.

The commands below do not run a contract. ridl checks your declarations and generates code from them. The only runtime in this repository is ridl-loopback, which runs inside one program; no command here starts it.

1. Install the toolchain

On Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/driftsys/ridl/main/install.sh | bash
ridl --version

On Windows, run install.ps1 from PowerShell instead. The environment variables that choose the install directory and the release, and the option of building from a clone, are in Installing the toolchain. The editor and the agent tools are in Editor and agent setup.

2. Create a package

ridl new demo

ridl new creates the directory demo and writes two files into it. Use ridl init to write the same files into a directory that already exists, and --workspace to write a workspace root with one member instead of a standalone package. The flags and the cases where the command refuses are in the CLI reference.

demo/ridl.toml is the manifest. It names the package and its version, and it ends with a commented-out [backend.rust] table that step 5 uses.

demo/demo.ridl is the source file:

package demo

/// Road speed.
type Speed: km/h [0.0..250.0 step 0.5]

/// Reports speed.
interface Hello {
  /// Current speed, every 10 ms.
  signal speed: Speed @10ms
}

The first line names the package. A package name must equal the directory path below the workspace root, and every file in the directory declares the same name. Speed is a scalar type with a unit and a range, and Hello is an interface with one signal whose contract requires the provider to publish it every 10 ms. The typl reference and the ridl reference define every form.

3. Check it

ridl check demo

ridl check reads the package and prints the diagnostics it draws. It exits 0 when none is an error and 1 when one is. To see an error, change Speed to Sped in the signal and run the command again: it prints TYPL-011 (unknown type name) with the file, the line and the column. The ridl check reference lists the flags and the exit codes, and the lints chapter describes the warnings that you can raise or lower.

4. Format it

ridl fmt --check demo

ridl fmt rewrites the sources into the canonical layout, and --check writes nothing and exits 1 when a file differs. The scaffold already conforms.

5. Build it

ridl build demo

ridl build writes the Rust crate under out in the current directory: Cargo.toml, lib.rs and one file for the package. With no [backend.rust] table in the manifest, the crate holds the domain types only. To also generate the FlatBuffers codec, the descriptors and the interaction face, uncomment the table in demo/ridl.toml:

[backend.rust]
encodings = ["flatbuffers"]

and build again. Other targets, such as TypeScript and the IR, are chosen with --emit; see ridl build.

Where to go next

• To learn the language, work through Getting started.
• To link the crate that step 5 wrote from a program and run it, read From a package to a running program.
• To use the crate in every form, read Using the generated Rust code.
• To describe components, wiring and deployments, read Describing a system.
• To change an interface after you published it, read Evolving an interface.
• To see what stays fixed across the 0.10.x releases, read Stability.

From a package to a running program

First steps ends at a generated crate. This chapter goes on: it links that crate from a Rust program and runs the program. It states each step once and links to the chapter that owns the detail.

What runs here. The program runs in one process. The only runtime in this repository is ridl-loopback, which connects the faces of one program to each other; no network runtime exists, so nothing below delivers a message between processes, measures a timing bound, or enforces a contract on a remote provider. Using the generated Rust code says what a call does over ridl-loopback.

The schema

The scaffold of First steps has one signal. A program that shows every kind of interaction needs a schema with more, so this chapter uses the worked example examples/cabin of the repository. Its schema declares a signal, an event, a command and a query:

package veh.cabin

/// Cabin air temperature, in degrees.
type Temperature: integer [-40..85]

/// A percentage of full scale.
type Level: integer [0..100]

/// An averaging window, in milliseconds.
type Window: integer [0..100000]

/// The average a query replies with. Its range is wider than `Level`'s,
/// so a reply is not constrained to the scale the command takes.
type Average: integer [0..1000]

/// The health of a cabin subsystem.
enum Health {
  /// The subsystem works normally.
  OK = 0
  /// The subsystem works, with a fault that needs attention.
  WARN = 1
  /// The subsystem does not work.
  FAIL = 2
}

/// Raised when a subsystem leaves `OK`.
struct Warning {
  /// The warning code, as a percentage of full scale.
  code: Level
  /// The health the subsystem moved to.
  health: Health
}

/// The cabin's own interface: a signal, an event, a command and a query, so
/// the proof covers every interaction kind that carries a payload.
interface Cabin {
  /// The current cabin air temperature.
  signal temperature: Temperature @10ms
  /// Sent when a subsystem leaves `OK`.
  event warning: Warning @[100ms..1s]
  /// Sets the cabin level, below 100.
  command setLevel(level: Level) @[..50ms] [
    require level < 100
  ]
  /// The average level over the window, in milliseconds.
  query average(window: Window): Average @[..200ms] [
    require window > 0
    ensure result >= 0
  ]
}

The manifest of that example names the encoding that the face needs, with the [backend.rust] table that step 5 of First steps shows:

[package]
name = "veh.cabin"
version = "1.0.0"

[backend.rust]
encodings = ["flatbuffers", "proto3", "podbuf"]

The face needs one of the encodings; the example lists all three so that the program can also encode a value with podbuf. Do the same in your own package: uncomment the table in ridl.toml, and the build writes the codec, the descriptors and the face.

Generate the crate

ridl build examples/cabin --emit rust --out-dir generated

The crate is named after the package, with each . replaced by _, so this one is veh_cabin. Using the generated Rust code lists what it holds.

Link the crate

A Rust package names the generated crate by path, ridl-loopback for the ports, and ridl-rt for the items the program uses from it. This Cargo.toml fragment is an illustration and is not compiled; the program that just demo builds has the same three dependencies in examples/cabin/consumer/Cargo.toml:

[dependencies]
veh_cabin = { path = "generated", features = ["std"] }
ridl-loopback = "0.14.0"
ridl-rt = { version = "0.14.0", features = ["std"] }

The program imports CatalogRef, Interface and Provenance from ridl-rt and calls ridl_rt::task::noop_waker, which exists only under the std feature of ridl-rt. The std feature of the generated crate is on by default and is named here so the dependency is explicit. The features of each crate are in Cargo features.

Write the program

The face is a set of types that the program imports. prelude brings the traits of the face into scope; without it, Client::new does not compile:

use api::cabin;
use api::cabin::prelude::*;
use ridl_loopback::Loopback;
use ridl_rt::contract::{CatalogRef, Interface};
use ridl_rt::encoding::Podbuf;
use ridl_rt::payload::{Payload, Ref};
use ridl_rt::sample::Provenance;
use veh_cabin::veh::cabin as api;

A runtime gives out ports, and each face binds one. Loopback::new takes the catalog that the face was generated from, which CATALOG holds in the program:

    let rt = Loopback::new(CATALOG);
    let mut publisher = cabin::Publisher::new(rt.attach());
    let mut client = cabin::Client::new(rt.attach());
    let mut blocking_client =
        cabin::blocking::Client::new(rt.attach()).with_timeout(CLIENT_TIMEOUT);
    let mut handler = rt.handler();
    let mut provider = Cabin {
        levels: Vec::new(),
        average: api::Average::new(7).expect("7 is inside Average's range"),
    };

The first interaction is the signal. The publisher side publishes a value and commits it, and the client side reads it. new checks the typl range of Temperature and returns an error for a value outside it:

    {
        publisher
            .temperature(api::Temperature::new(21).expect("21 is inside Temperature's range"))
            .expect("publish temperature");
        publisher.commit();
        let sample = client.temperature().expect("read temperature");
        assert_eq!(sample.value.get(), 21);
        assert_eq!(sample.provenance, Provenance::Live);
        println!("signal ok {}", sample.value.get());
    }

A command and a query need a provider. The program implements the trait that the face generates, and the face calls it only with a request that passed its checks:

struct Cabin {
    levels: Vec<i64>,
    average: api::Average,
}

impl cabin::Provider for Cabin {
    fn set_level(&mut self, level: &api::Level) {
        self.levels.push(level.get());
    }
    fn average(&mut self, _window: &api::Window) -> api::Average {
        self.average
    }
}

The rest of the program, which sends the command and the query through the async client and through the blocking client, is explained in Using the generated Rust code.

Run it

From a clone of the repository, just demo generates the crate, runs clippy, the no_std checks and the documentation build on it, and then runs the program. To run only the program, generate the crate as above and then:

cargo run --manifest-path examples/cabin/Cargo.toml -p consumer

The program prints one line per round trip. Each line carries the value that the round trip moved, and the program exits with a non-zero status when a value is not the expected one. The last line comes from a value that goes through the generated podbuf codec alone, without the runtime: the program encodes it, verifies the bytes and decodes it again:

signal ok 21
event ok 5
command ok 42
query ok 7
blocking command ok 43
blocking query ok 9
podbuf round trip: 21.5

Where to go next

• To call the interface in every form, and to implement a provider, read Using the generated Rust code.
• To connect a face to a transport of your own, read Writing a port.
• To change an interface after you published it, read Evolving an interface.

Getting started

A practical introduction to ridl, the interface description language of the RIDL family. It is written for engineers who describe the contracts between software components — in a vehicle, or in any component-based reactive system.

Every ridl code block in this chapter is compiled by the repository's test suite against the toolchain in this repository, and must draw no diagnostic beyond the ones its own fence names. If a block is shown here, it compiles. The prose around the blocks is not machine-checked; where it describes behaviour rather than syntax, read the note below first.

What ridl is

ridl answers one question about a service: what does it produce, consume, and guarantee?

A .ridl file describes an interface — not an implementation. It does not say how a service works internally, only what it exposes at its boundary. That is what makes it usable as the single source of truth between teams, components, and tools.

ridl is transport-neutral by design: the same contract is intended to bind to SOME/IP, gRPC, DDS, MQTT, or AIDL without modification. The transport bindings are specified in the ridl language reference, Appendix B. They are not implemented yet. What the compiler emits today is listed under What the compiler produces.

What "the contract requires" means in this chapter

Several sections below describe what happens when a contract runs: that a subscriber is delivered the last value, that an occurrence past its staleness bound is discarded, that a provider checks a require clause before your code sees the call. Every one of those is a requirement the specification places on a runtime and its transport bindings, and no command in this chapter runs one. The repository does hold an in-process runtime, ridl-loopback, which carries a last value from a provider to a consumer inside one program; it measures nothing against a staleness bound, and nothing the compiler emits links it. So what you run below neither delivers a message nor enforces a contract.

The sentences are written in the present tense because they describe what the contract means, which is the thing you are designing against. They do not describe behaviour you can observe today. What you can observe today is the toolchain: it checks your declarations, generates data types, samples your require clauses, and classifies changes between versions. Where a comment inside a listing says a binding "must discard" an occurrence, read it as what the contract demands of a binding, not as something running.

ridl is one language of five

ridl does not define types. It references them. The vocabulary layer is a separate language, typl, and the two are used together: a .ridl file accepts every typl declaration in addition to its own interaction declarations.

This chapter covers typl and ridl; Describing a system covers rsdl. Where this chapter mentions rxdl or rmdl, it is describing a plan.

Installing the toolchain

Released binaries of ridl and ridlc are attached to the GitHub Releases tagged editor-v<version>. On Linux and macOS, install.sh downloads the newest one, verifies its SHA-256 checksum, and installs it. It supports x86_64 and aarch64 Linux and x86_64 and arm64 macOS, and exits with unsupported platform on any other:

curl -fsSL https://raw.githubusercontent.com/driftsys/ridl/main/install.sh | bash

On Windows, run install.ps1 from PowerShell. It installs the x86_64 build:

irm https://raw.githubusercontent.com/driftsys/ridl/main/install.ps1 | iex

Both scripts read the same environment variables:

When the install directory is not on your PATH, the script prints the command that adds it.

This book describes the main branch, which can hold features the newest release does not. To get everything this book describes, build the two binaries from a clone of this repository:

cargo build --release

That produces target/release/ridl — the command you will use — and target/release/ridlc, the compiler underneath it. Put ridl on your PATH, or call it by path. cargo install --path crates/ridl installs ridl alone.

Editor and agent setup

VS Code. The RIDL extension is published to the VS Code Marketplace and to Open VSX under the name "RIDL". It highlights .typl, .ridl and .rsdl files and runs the language server. It bundles a ridl binary and starts it as ridl lsp, so it needs no separate install. The command RIDL: Install ridl to PATH copies the bundled binary to ~/.local/bin (%LOCALAPPDATA%\Programs\ridl on Windows). When that directory is not on your PATH, the command warns and offers a command that adds it. The setting ridl.serverPath names a different ridl binary to run, for both ridl lsp and ridl mcp; empty, the default, uses the bundled binary, or ridl on PATH when none is bundled. The setting ridl.trace.server (off, messages or verbose) traces the traffic between the editor and the server. The extension README lists the features.

Other editors. ridl lsp serves the Language Server Protocol over stdio, the only transport it supports. Configure your editor's language-server client to run ridl lsp for .typl, .ridl and .rsdl files. ridl lsp in the CLI reference states the accepted flags and exit codes.

Agent hosts. ridl mcp serves the Model Context Protocol over stdio, with read-only tools that check, explain and inspect a workspace. It takes no flag. An MCP-aware agent host starts it as a plain command and arguments:

{ "command": "ridl", "args": ["mcp"] }

Each host wraps this in its own format, in its own file. Claude Code reads it from the project's .mcp.json (or claude mcp add ridl -- ridl mcp writes it):

{
  "mcpServers": {
    "ridl": { "command": "ridl", "args": ["mcp"] }
  }
}

Codex reads it from ~/.codex/config.toml:

[mcp_servers.ridl]
command = "ridl"
args = ["mcp"]

The command ridl must be on the PATH the host uses. The RIDL extension needs VS Code 1.109 or newer, and registers ridl mcp automatically, so GitHub Copilot in VS Code needs no configuration.

The authoring skill. Each editor release attaches ridl-authoring-<version>.zip, a skill that teaches an agent to write and review RIDL and to check its work with the ridl MCP server. For Claude Code, unpack it into ~/.claude/skills/ or into a project's .claude/skills/; for Codex, into ~/.codex/skills/. The VS Code extension already contains the skill for GitHub Copilot.

ridl mcp lists the tools, and the ridl-mcp README documents their input and output schemas.

A workspace

A package is a directory, and every package carries a ridl.toml manifest. A workspace groups several packages under a root manifest that lists them.

The tutorial builds this layout:

tutorial/
├── ridl.toml                 the workspace root
└── veh/
    ├── common/
    │   ├── ridl.toml
    │   ├── types.ridl        the shared vocabulary
    │   └── scalars.ridl
    ├── cluster/
    │   ├── ridl.toml
    │   └── cluster.ridl      the interfaces
    ├── identity/             annex 1
    ├── powertrain/           annex 2
    ├── body/                 annex 3
    └── dms/                  annex 4

The root manifest lists every member. Start with the two the tutorial builds first, and add the annex packages as you reach them:

[workspace]
members = ["veh/common", "veh/cluster"]

Each member names itself and its version:

[package]
name = "veh.common"
version = "1.0.0"

The package name mirrors the directory path below the workspace root, and every file in the directory declares that same name. A mismatch is a hard error (TYPL-002).

A package that lives in another repository is named in an [imports] table of the root manifest, under the key its ridl.toml declares as its name:

[imports]
"veh.common" = "https://registry.example.com/veh/common@v1.0.0"

ridl check fetches it once into ~/.ridl/cache, pins it in ridl.lock, and from then on reads the cache until vendor/ holds the unit; import veh.common.Speed then resolves as it does for a member. ridl vendor copies each unit into vendor/ beside ridl.toml, after which ridl check reads that copy first, so a ridl check --frozen on a machine with no network and no cache still builds; ridl vendor --check verifies that directory in CI. A remote unit is a read-only dependency: its errors fail the check, its warnings are not shown, and ridl build generates it beside your own packages. The Remote units and ridl vendor chapter is the guide, and the CLI reference says what each command writes.

You can run ridl from the workspace root or from inside a member. A command started in veh/cluster finds the root manifest that lists veh/cluster, so the member still sees veh.common, and the root's settings apply to it. The check then reports only the diagnostics of files in veh/cluster.

To start a project of your own, ridl new scaffolds one. Run it outside the tutorial workspace, for example from the directory that holds tutorial/, because it refuses a directory that sits inside an existing unit. It creates the directory and writes a ridl.toml and a small .ridl file that already checks:

ridl new demo
ridl check demo

ridl init does the same inside a directory that exists, and --workspace writes a workspace root with one member instead of a standalone package. Both refuse, and write nothing, when a file they would write exists or when the directory sits inside, or above, another unit. The CLI reference lists the flags and the refusals.

The manifest ends with a commented-out [backend.rust] table. Until you uncomment it, ridl build --emit rust generates the types only; with it, the build also generates the FlatBuffers codec, the descriptors and the interaction face. With --workspace, the table is in the workspace root's manifest, not the member's.

Your first vocabulary

Create veh/common/types.ridl:

package veh.common

/// Road speed of the vehicle.
type Speed: km/h [0.0..250.0 step 0.5]

That is a complete package. type Speed: km/h [0.0..250.0 step 0.5] declares a named scalar with a physical unit (UCUM km/h), a closed range, and a quantization step.

Your first interface

Create veh/cluster/cluster.ridl:

package veh.cluster
import veh.common.Speed

/// Vehicle speed reporting interface.
interface VehicleSpeed {
  /// Current vehicle speed, published every 10 ms.
  signal currentSpeed: Speed @10ms
}

Line by line:

• package veh.cluster — this file belongs to the veh.cluster package.
• import veh.common.Speed — Speed is declared in another package. Imports are single-type and qualified; there are no wildcards and no relative imports.
• interface VehicleSpeed — the contract boundary.
• signal currentSpeed: Speed @10ms — a continuously published value, whose contract requires the provider to publish it every 10 ms.

Checking it

From the workspace root:

ridl check

ridl check type-checks a file, a package directory, or a whole workspace, and defaults to the current directory. It exits 0 when nothing is wrong, 1 when a diagnostic is an error, and 2 when it cannot even load the workspace — for example when no ridl.toml is found.

Swap the bounds in types.ridl to [250.0..0.0 step 0.5] and run it again:

error[TYPL-104]: range minimum 250 is greater than maximum 0
  ┌─ ./veh/common/types.ridl:4:18
  │
4 │ type Speed: km/h [250.0..0.0 step 0.5]
  │                  ^^^^^^^^^^^^^^^^^^^^^

Most diagnostics carry a stable code. TYPL- codes come from the vocabulary layer, RIDL- codes from the interaction layer, FORM- codes from the shared surface syntax, and MANI- codes from the manifest. Those codes are listed in the language references and are never renumbered or reused. A few diagnostics are still uncoded and print as a bare error: — a constant written where a type is expected is one — so do not assume a code is always there to search for.

Primitives and named types

typl has five primitives: boolean, integer, float, string, bytes.

In an interaction, a primitive is never written directly. A signal payload, an event payload, a command or query parameter, and a fixed value must each name a type. Writing fixed doorCount: integer [1..8] is a FORM-102 error; declare type DoorCount: integer [1..8] and use the name. This is the single rule that most often surprises newcomers, and it is what gives every value on the boundary a domain meaning rather than a width.

Struct fields are more permissive. An inline constrained primitive is accepted there, including string [1..10] and bytes [64] — what the compiler rejects in a field is a bare string or bytes with no constraint at all (TYPL-208). The typl reference states the rule without that qualification, so trust the compiler here: the constraint is what the check is about, and the reference's own Appendix B writes frame : bytes [8]. Named types remain the recommendation everywhere, and they are mandatory on a boundary.

Add a second file, veh/common/scalars.ridl.

package veh.common

// physical unit types — UCUM units
type Temperature: Cel [-40.0..125.0 step 0.1]

type FuelLevel: % [0.0..100.0 step 0.1]

type Voltage: V [0.0..48.0 step 0.1]

type Ratio: % [0.0..100.0 step 0.1]

// constrained integer types
type Counter: integer [0..65535]

type DoorIndex: integer [0..7]

type DoorCount: integer [1..8]

type Severity: integer [0..5]

// a named boolean, so it can be used on a boundary
type Enabled: boolean

// string types — bounds are recommended everywhere and required on a boundary
type ModelCode: string [3..6 match MODEL_PATTERN] = "ABC"

type Notes: string [1..256] = "-"

type Vin: string [17 match VIN_PATTERN] = "1HGCM82633A004352"

Two details in that listing:

• The range drives the wire width. integer [0..255] is a uint8 on transport; integer [0..65535] is a uint16. The generated language type is always int64. You never write a width.
• = "ABC" is an init value — the value a consumer holds before anything real arrives. It is derived automatically for most types: false for booleans, 0 for a number whose range contains it and the range minimum otherwise, and the empty value when a string or bytes bound allows length 0. It cannot be derived for a string or bytes type carrying a match pattern or a non-zero minimum length, so those declare one — which is why ModelCode, Notes and Vin above do. Without a declared init such a type draws a TYPL-115 note. That note stays informational, always; what turns a missing init into an error is using the type as a signal payload, and the error is RIDL-109, raised at the signal.

Standard library types are always available without an import: Uuid, Ulid, Uri, Url, Email, Label, Name, Message, Timestamp, Duration, Version, Date, CountryCode, Sha256Hash, and others. They live in the implicitly imported ridl.std package.

ridl.std holds only what is fixed by a cross-industry standard and means the same in every domain, because it is in scope in every file you write. A type that belongs to your industry — Vin above — is declared in your own vocabulary package, like any other domain type.

Constants

const declares a compile-time constant, reusable in range bounds, match patterns, init values, and contract expressions:

package veh.common

const MAX_SPEED: Speed = 250.0

const SPEED_LIMIT_EU: Speed = 130.0

const MAX_GEAR: integer = 6

// regex constants
const MODEL_PATTERN = /^[A-Z][A-Z0-9]{2,5}$/

const VIN_PATTERN = /^[A-HJ-NPR-Z0-9]{17}$/

// reuse in a range bound
type EngineSpeed: km/h [0.0..MAX_SPEED step 0.5]

struct GearState {
  gear: integer [0..MAX_GEAR]
}

Constants are written SCREAMING_SNAKE by convention. The compiler does not enforce it — the lexer folds every case shape into one identifier kind, so a lower-case constant name compiles. The declared value, on the other hand, must satisfy the constant's own type constraints, and that is checked.

Signals and events

The split between signal and event is the load-bearing distinction in ridl. It is a distinction in meaning, which the specification then turns into demands on a binding (see the note above; of the bindings, the WebSocket one is built):

• A signal is continuous state. The latest sample is the truth, and an intermediate sample may be missed. The contract requires the channel never to be empty: a new subscriber must be delivered a value immediately — the init value before the first publication, the latest value after it.
• An event is a discrete occurrence. Every occurrence matters, so the contract requires occurrences to be queued rather than coalesced, and forbids late-joiner delivery. An occurrence that happened before you subscribed did not happen to you.

package veh.cluster
import veh.common.Speed
import veh.common.Temperature
import veh.common.FuelLevel
import veh.common.SPEED_LIMIT_EU

/// The three timing forms a signal accepts.
interface Sampling {
  /// Strict periodic — published every 10 ms whether or not it changed.
  signal currentSpeed: Speed @10ms

  /// Change-driven — not faster than 20 ms, refreshed at least every 100 ms.
  signal engineTemp: Temperature @[20ms..100ms]

  /// Staleness bound only — refreshed at least every 5 s.
  signal fuelLevel: FuelLevel @[..5s]

  /// An init value override, written as a bare `= value` before the timing.
  signal targetSpeed: Speed = SPEED_LIMIT_EU @[20ms..500ms]
}

The bounds have one meaning everywhere: min is the rate floor, the minimum interval between publications, and max is the staleness bound, the maximum age of the value. Those two bounds are what the compiler records in the IR, and they are all it records. What a binding is required to do at each bound follows from the declaring keyword — specified, not implemented:

Events take a range only. Strict periodic @Xms on an event is a RIDL-103 error, because an isochronous rate is meaningless for occurrences:

package veh.cluster
import veh.common.DoorIndex

struct DoorPayload {
  sensorId: DoorIndex
  isOpen: boolean
}

interface DoorEvents {
  /// Raised on every door state change; a binding must treat it as stale
  /// 500 ms after it was raised.
  event doorOpened: DoorPayload @[50ms..500ms]

  /// A binding must throttle to one occurrence per 100 ms, and must discard
  /// one that reaches a consumer more than 2 s after it was raised.
  event speedLimitExceeded: DoorPayload @[100ms..2000ms]
}

A signal or event with no @ annotation is not rejected — it receives the default range @[100ms..1000ms] and draws a RIDL-100 warning. The default is configurable per package or per workspace:

[defaults]
timing = "[100ms..1000ms]"
command_timing = "[..1s]"
query_timing = "[..3s]"

A command or query with no response bound is treated the same way: it receives command_timing (built-in [..1s]) or query_timing (built-in [..3s]) and draws RIDL-112. Each key resolves on its own.

Because the IR always carries resolved bounds, changing a default changes every untimed interaction it covers in the package, and ridl diff reports it as a contract change. Safety-graded packages should annotate every interaction explicitly.

Enums and enum sets

An enum is an integer-backed set of discrete values, for choosing one:

package veh.common

enum GearPosition {
  PARK = 0
  REVERSE = 1
  NEUTRAL = 2
  DRIVE = 3
  LOW = 4
}

enum DriveMode {
  NORMAL = 0
  ECO = 1
  SPORT = 2
  OFF_ROAD = 3
}

Newline and comma are interchangeable separators everywhere, so both layouts above are the same declaration. There are no semicolons in the language.

An enumset is a named bitfield, for several flags at once:

package veh.common

enumset AccessFlags {
  DOOR_UNLOCKED = 0 // bit 0
  BOOT_UNLOCKED = 1 // bit 1
  WINDOW_OPEN = 2 // bit 2
}

When you need both the single value and the set, declare the enum and derive the enumset from it:

package veh.common

enum Warning {
  LOW_FUEL = 0
  CHECK_ENGINE = 1
  DOOR_OPEN = 2
  SEATBELT = 3
}

enumset WarningFlags: Warning

Both names are then usable on a boundary — the enum where one value is meant, the enumset where several are:

package veh.cluster
import veh.common.Warning
import veh.common.WarningFlags

interface Warnings {
  command clearWarning(flag: Warning) @[..50ms]
  signal activeWarnings: WarningFlags @[50ms..1s]
}

Provisioned values — fixed

A fixed is a value set at build, factory, or over-the-air update, and immutable for the lifetime of the running software instance:

package veh.cluster
import veh.common.DoorCount
import veh.common.Enabled
import veh.common.Vin

interface VehicleIdentityBasics {
  fixed vin: Vin
  fixed softwareVersion: Version
  fixed marketRegion: Label
  fixed ecuSerial: Uuid
  fixed capabilities: [Label; 0..32]
  fixed doorCount: DoorCount
  fixed hasCruise: Enabled
}

Declaring a value fixed is a promise that it never changes while the software runs, which is what makes it safe for a consumer to cache unconditionally — a promise to a future binding, like the rest of the delivery semantics. What the compiler enforces today is the shape: a fixed takes no timing annotation and no contract block, and both are RIDL-106 errors. Note hasCruise: Enabled rather than hasCruise: boolean: a boundary value names a type.

Commands and queries

A command is a fire-and-forget action request. It never returns a value — writing a return type is a RIDL-104 error. If the caller needs to know the outcome, the outcome is observed as state, or the interaction is a query.

A query is request/response. The reply is mandatory, and a query returning () is a RIDL-105 error.

package veh.cluster
import veh.common.Speed
import veh.common.GearPosition

interface Control {
  command setTargetSpeed(speed: Speed) @[..50ms]
  command enableCruiseControl() @[..50ms]
  command resetFaults() @[..200ms]
  command setGear(position: GearPosition) @[20ms..100ms]

  query getCurrentSpeed(): Speed @[..50ms]
  query getSpeedHistory(window: Duration): (min: Speed, max: Speed, avg: Speed) @[..100ms]
}

A query return may be a named type, a tuple of named fields, a stream, or an inline T | E union that makes the query fallible. Parameters are named types or streams — a tuple is not a parameter type; pass a struct.

A command or query takes the same @[min..max] range a signal does, with the same two bounds read for a call: min is the call throttle — the caller must not call faster — and max is the response bound — the provider must respond within it. For a query, responding is the reply; for a command it is acceptance, the delivery acknowledgment, not execution. setGear above declares both: callers throttle to one request per 20 ms, and the provider accepts within 100 ms. Only the range form is admitted — a strict periodic @Xms on a command or query is a RIDL-103 error, because a caller is not isochronous by contract.

Like a signal, an RPC with no declared response bound takes a default: the package's command_timing or query_timing, else the built-in [..1s] for a command and [..3s] for a query. It still draws a RIDL-112 warning, and the IR carries the resolved bound. @[20ms..] — a throttle with no response bound — warns the same way and takes max from the default; a missing min draws nothing.

Structs and optionality

package veh.common

struct CruiseControlState {
  enabled: boolean
  targetSpeed: Speed
  mode: DriveMode
  override: Speed? // optional — absent when no override is active
}

The ? suffix means may be absent, which is not the same as present-and-null; typl has no null.

Struct fields carry implicit ordinals by declaration order, so evolution is append-only: add new fields at the end, and retire a removed field with a reserved tombstone so its slot is never reused.

package veh.common

struct DriverProfile {
  name: Name
  reserved legacyChecksum // was ordinal 2 — retired, never reused
  speed: Speed
}

Structs may not be recursive: an unbounded wire size would contradict the bounded-size guarantee every typl composite carries.

Errors are data

ridl has no throws, no exceptions, and no status codes. A query that can fail as part of its domain semantics says so in its return type, using vocabulary declared in typl:

package veh.common

/// Failure vocabulary — the `error` modifier marks a shape as a failure shape.
error enum CalError {
  SENSOR_UNAVAILABLE = 0
  VEHICLE_MOVING = 1
  OUT_OF_RANGE = 2
}

struct CalReport {
  offset: float [-1.0..1.0 step 0.001]
}

struct Axle {
  index: integer [0..3]
}

package veh.cluster
import veh.common.CalError
import veh.common.CalReport
import veh.common.Axle

interface Calibration {
  /// Fallible query — the inline `T | E` return is the canonical spelling.
  query calibrate(axle: Axle): CalReport | CalError @[..5s]
}

The left arm is the success type, the right arm exactly one error type.

One half of what follows from that you can see today: the Rust backend renders the fallible return as a Result<T, E>, so exhaustive handling is enforced by the compiler you already use. The other half is specified only — a binding is required to split the union mechanically, sending the success arm as the reply payload and mapping the error arm onto the transport's own error channel. No binding is built to do it.

Two other failure kinds never appear in source at all, and both belong entirely to that unbuilt layer. Contract violations — a payload outside its declared range, or a failed require — are derived from the declarations you already wrote, and the specification requires a runtime to report them uniformly rather than making you declare them. Transport failures — timeouts, broker loss, connection resets — are infrastructure failures the specification requires a runtime to detect and leaves undeclared in the language, because a contract author has no knowledge to express about them.

Collections and streams

Collections are finite and always explicitly bounded:

package veh.common

struct FaultCode {
  dtc: integer [0..65535]
}

struct DiagReport {
  faults: [FaultCode; 0..32] // bounded array — at most 32 faults
  sensors: [Label: Speed; 1..8] // bounded map — 1 to 8 entries
  readings: [Speed; 8] // fixed array — exactly 8
  rawFrame: bytes [64] // fixed 64-byte buffer
}

A stream <T> is the one unbounded container, and it is valid only in interaction position — on a command or query parameter, or a query return. Its element type is a named type describing one logical element; framing and backpressure are transport concerns.

package veh.common

type LogLine: string [1..1024] = "-"

type FwBlock: bytes [1..4096]

struct SensorSample {
  value: Speed
}

struct ProcessedSample {
  value: Speed
}

struct DiagFilter {
  severity: Severity
}

FwBlock draws a TYPL-115 note: bytes with a minimum length above zero has no derivable init value, exactly as a string with a minimum length above zero or a match pattern does. The note is harmless here — a stream element is never a signal payload, so nothing ever asks it for an init — and the block's fence carries allow=TYPL-115 to say so.

package veh.cluster
import veh.common.LogLine
import veh.common.FwBlock
import veh.common.DiagFilter
import veh.common.FaultCode
import veh.common.SensorSample
import veh.common.ProcessedSample

interface Transfer {
  query streamFaults(filter: DiagFilter): <FaultCode> @[..1s] // provider produces
  query streamLogs(): <LogLine> @[..1s] // text stream
  command uploadFirmware(data: <FwBlock>) @[..1s] // consumer produces
  query pipe(samples: <SensorSample>): <ProcessedSample> @[..1s] // bidirectional
}

Direction follows position. A stream in return position is declared to flow from provider to consumer, one in parameter position the other way, and a query with both declares full duplex. That is a statement about the contract; nothing flows until a binding exists to carry it. A stream on a signal or an event is a RIDL-201 error — a signal is the better stream for state, and an unbounded push of occurrences is an event.

Contracts

require and ensure clauses go in an attribute block after a command or a query. require is a precondition over the parameters and the interface's own signals; ensure is a postcondition over result, and is valid on queries only.

package veh.cluster
import veh.common.Speed
import veh.common.SPEED_LIMIT_EU

interface Cruise {
  signal currentSpeed: Speed @10ms

  command setTargetSpeed(speed: Speed) @[..50ms] [
    require speed > 0.0
    require speed <= SPEED_LIMIT_EU
  ]

  query getSpeedHistory(window: Duration): (min: Speed, max: Speed, avg: Speed) @[..100ms] [
    require window > 0ms
    ensure result.min <= result.avg
    ensure result.avg <= result.max
  ]
}

Contract expressions are type-checked, unquoted, and side-effect-free. They are restricted to a guaranteed subset: comparison, boolean connectives, arithmetic, enum access, tuple-field access, and duration comparison, over parameters, result, constants, enum values, and the interface's own signals. Anything outside it is a RIDL-306 error. Reading a field of a struct-typed signal is outside the subset — publish the scalar you want to constrain as its own signal instead.

The clauses are not documentation, and one use of them runs today: ridl test draws sample parameter tuples and evaluates each require clause against them. It does not evaluate ensure clauses — it lists them as observer stubs, because checking a postcondition needs a result, and producing one needs the runtime that does not exist yet. That same unbuilt layer is where the specification puts the other use: a provider binding evaluating require before your code runs, and ensure after it returns.

Labels

@labels is a doc-comment tag carrying free-form classification identifiers — safety, security, privacy, or any other domain-specific tag. The core language defines no vocabulary:

package veh.cluster
import veh.common.Speed

/// Cruise control interface.
/// @labels SIL_2, SEC_2, PRIVATE
interface CruiseControl {
  signal engagedSpeed: Speed @[50ms..500ms]
}

/// Logging interface — no safety or security requirement.
/// @labels SIL_QM, SEC_NA, PUBLIC
interface LogService {
  signal lastSpeed: Speed @[1s..10s]
}

Different domains use different vocabularies: an automotive profile would define ASIL_*, a medical profile IEC_62304_*, an industrial profile IEC_61508_*.

As built, labels are carried through unchecked. The compiler parses them and passes them into the IR unchanged. The assurance profiles that would validate a vocabulary and its combinations (diagnostics TYPL-402 and TYPL-403) are specified but not implemented.

What the compiler produces

ridl build --emit rust --out-dir out

ridl build compiles a workspace and writes one artifact per package for each emit target, except that catalog writes one per unit and none for a unit that declares no interface and no service with an inline body. Eleven emit targets exist today:

One more artifact joins them when a package names a type from ridl.std — Duration above does — because generated code refers to standard types by package path and does not compile without the standard package beside it. The command above therefore writes out/ridl.std.rs as well, and --emit typescript writes ridl.std.ts the same way (and ridl.std.codec.ts under [backend.typescript] codec = true, when a codec module imports it). The three IR targets are an exception: a direct IR dump records the packages the workspace declares, and ridl.std ships with the compiler. catalog is the other exception: ridl.std declares no interface, so no ridl.std.catalog.binfb is written.

Using the generated Rust code shows how a program calls the crate that --emit rust writes, and The catalog descriptor explains the catalog file.

There is no transport binding and no code generator for SOME/IP, gRPC, DDS, MQTT or AIDL yet. Those mappings are specified in the ridl language reference, Appendix B, and are the work of later epics.

Classic CAN is not on that list, and never will be for a whole interface: Appendix B records that DBC/CAN binds signal declarations only, and that an event, command or query on classic CAN is a profile error. A bus carries dataflow, not calls.

The rest of the toolchain

ridlc is the plumbing underneath, with check and build only. Use ridl unless you are scripting the compiler directly.

Two of those deserve a note.

ridl fmt applies the canonical layout used by this chapter's verified listings. It tightens colons and spacing and places one member per line in brace bodies. The CLI reference describes the two-space indentation and configurable line width, which defaults to 100 characters.

ridl diff classifies, and its exit code carries the answer: 0 when the change is compatible or the snapshots are identical, 1 when it is breaking, 2 on an error. Interactions carry implicit ordinals by declaration order, so appending is compatible and inserting or reordering is not. Retire an interaction with a reserved tombstone rather than deleting it:

package veh.cluster
import veh.common.Speed

// `DoorPayload` is declared earlier in this same package (`veh.cluster`), so
// it needs no import — everything in a package is visible to the rest of it.

interface VehicleStatus {
  signal currentSpeed: Speed @10ms
  reserved legacyTemp // was ordinal 2 — retired
  event doorOpened: DoorPayload @[50ms..500ms]
}

ridl check also compares against a published baseline when .ridl/baseline/ exists, and reports a moved ordinal as a RIDL-407 warning at your desk, before CI sees it.

Interfaces and services

An interface is an abstract shape: a reusable, identity-less group of interactions. It is not addressable and not deployed.

A service is a global, named, published declaration of one or more of them — the catalog entry that gives contracts a concrete identity in the system. The specification defines its members as addressed service.member; no runtime resolves such an address today, so read it as the naming scheme a deployment will use. Service names are unique across the system and always public, and that uniqueness the compiler does enforce (RIDL-140).

package veh.cluster
import veh.common.Temperature

service veh.cluster.status: VehicleStatus

service veh.cluster.dash: VehicleStatus, Warnings

service veh.cluster.hvac {
  signal temperature: Temperature @[1s..10s]
  command setTarget(temp: Temperature) @[..50ms]
}

The first form names existing interfaces — a comma-separated list, and the commas are required, the one place the family's separators are not optional: the list has no closing token, so it ends where the next declaration begins. The last form declares an inline shape for a one-off contract not worth a reusable interface. A service declaration says nothing about how the contract is realized on the wire — that is a deployment question, and rsdl's (see Describing a system).

Composing interfaces is how a recurring interaction set — a diagnostics block, a heartbeat — is reused without duplication: each composed interface keeps its own ordinal space, and its number comes from its unit's interfaces.lock, not from its place in the list, so the list is a set and its order carries nothing. Because members stay addressed service.member, two composed interfaces must not share a member name (RIDL-144).

Interfaces are flat: there is no interface inheritance. Sharing a shape is typl's job; a shared interaction set is composed at the service, never flattened into the interface, so that a base change can never renumber a derived contract's wire identity.

Naming conventions

Beyond spelling: name signals and fixed values as nouns (currentSpeed), events as past-tense occurrences (doorOpened), commands as imperatives (setGear), and queries as get… or stream…. A query named like a mutation draws a RIDL-404 warning, because it probably wanted to be a command.

Every registry word is reserved in every profile, including words this profile does not accept. state, states, model, component and the rest of the registry are not available as identifiers even in a .ridl file — the typl language reference §1.4 lists the whole set. The domain spellings of ADR-0012 (present, trigger, …) are not in the registry; they are identifiers until a profile implements one.

Next steps

• The ridl language reference — the normative interaction layer.
• The typl language reference — the normative vocabulary layer.
• The expr-core specification — the grammar of require and ensure.
• The family overview — the map, the shared doctrines, and the decision ledger.
• The four annexes below — complete, compiling interfaces from a vehicle domain.

Annex 1 — Vehicle identity

A pure fixed interface: everything provisioned at the factory or over the air. Note that every capability flag names a type rather than writing boolean, and that ModelYear and Speed are declared types, not inline ranges.

package veh.identity
import veh.common.Speed
import veh.common.Vin

type ModelYear: integer [2000..2100]

type Capability: boolean

enum FuelType {
  PETROL = 0
  DIESEL = 1
  HYBRID = 2
  ELECTRIC = 3
  HYDROGEN = 4
}

enum DriveLayout {
  FWD = 0
  RWD = 1
  AWD = 2
  FOUR_WD = 3
}

/// Vehicle identity and hardware capability manifest.
/// Provisioned at the factory. Software fields updated over the air.
///
/// @labels SIL_QM, SEC_2, CONFIDENTIAL
interface VehicleIdentity {
  // vehicle identity — factory provisioned
  fixed vin: Vin
  fixed modelYear: ModelYear
  fixed marketRegion: Label
  fixed fuelType: FuelType
  fixed driveLayout: DriveLayout

  // software identity — updated over the air
  fixed softwareVersion: Version
  fixed bootloaderVersion: Version
  fixed hardwareVersion: Version

  // capability flags — build time
  fixed hasAdaptiveCruise: Capability
  fixed hasEmergencyBraking: Capability
  fixed hasLaneKeepAssist: Capability
  fixed hasParkingAssist: Capability
  fixed hasDriverMonitoring: Capability
  fixed maxSupportedSpeed: Speed
}

Annex 2 — Powertrain

Two details worth reading closely. The engine's scalar speed is published as its own signal engineRpm, because a require clause may read a signal but not reach into a struct-typed one. And the engine state field is named engineState: state is a reserved word family-wide, so it cannot be an identifier. This annex also draws RIDL-414 (low-cohesion-interface): PowertrainManager keeps every powertrain fact behind one interface, and its members fall into seven groups that share no named type. The annex keeps that grouping to show one interface per subsystem.

package veh.powertrain

type RPM: /min [0.0..8000.0 step 10.0]

type Torque: N.m [0.0..500.0 step 0.1]

type Temperature: Cel [-40.0..150.0 step 0.1]

type FuelLevel: % [0.0..100.0 step 0.1]

type Voltage: V [0.0..48.0 step 0.1]

type Dtc: integer [0..65535]

type FaultCount: integer [0..65535]

type Severity: integer [0..5]

enum EngineState {
  OFF = 0
  CRANKING = 1
  RUNNING = 2
  FAULT = 3
}

enum GearPosition {
  PARK = 0
  REVERSE = 1
  NEUTRAL = 2
  DRIVE = 3
  LOW = 4
}

struct EngineMetrics {
  rpm: RPM
  torque: Torque
  oilTemp: Temperature
  coolantTemp: Temperature
  engineState: EngineState
}

struct TransmissionState {
  gear: GearPosition
  inputRPM: RPM
  outputRPM: RPM
  oilTemp: Temperature
}

/// The `timestamp` field records when the fault occurred, which is domain
/// information distinct from the envelope's publication time. `ridl check`
/// notes the overlap (RIDL-406); the note is informational and the field is
/// the legitimate exception the rule names.
struct FaultPayload {
  dtc: Dtc
  message: Message
  timestamp: Timestamp
}

/// Powertrain management interface.
///
/// @labels SIL_3, SEC_2, PUBLIC
interface PowertrainManager {
  signal engineMetrics: EngineMetrics @20ms
  signal engineRpm: RPM @20ms
  signal transmissionState: TransmissionState @[50ms..500ms]
  signal fuelLevel: FuelLevel @[..5s]
  signal batteryVoltage: Voltage @[100ms..1s]

  event engineFault: FaultPayload @[100ms..30s]
  event transmissionFault: FaultPayload @[100ms..30s]

  command requestStart(mode: EngineState) @[..200ms] [
    require mode == EngineState.CRANKING
  ]
  command requestStop() @[..200ms]
  command setGear(gear: GearPosition) @[20ms..100ms] [
    require gear != GearPosition.PARK || engineRpm == 0.0
  ]

  query getDiagnostics(): (
    engineState: EngineState,
    activeGear: GearPosition,
    faultCount: FaultCount,
    lastFaultTime: Timestamp
  ) @[..100ms]

  query streamFaults(severity: Severity): <FaultPayload> @[..1s]

  fixed softwareVersion: Version
  fixed calibrationVersion: Version
  fixed ecuSerial: Uuid
  fixed supportedGears: [GearPosition; 1..8]
}

Annex 3 — Body control

A signal payload is a single named type, so a collection of door states is published through a struct that wraps the array rather than as a bare array. Command parameters name types too: DoorIndex, not integer [0..7]. And the lock parameter is named lock, because state is reserved. BodyControl draws RIDL-414 (low-cohesion-interface): its members fall into ten groups that share no named type, which the annex keeps to show one interface per subsystem.

package veh.body
import veh.common.Temperature

type Ratio: % [0.0..100.0 step 1.0]

type DoorIndex: integer [0..7]

type DoorCount: integer [1..8]

type WindowCount: integer [0..8]

type UnlockCount: integer [0..8]

type Zone: integer [0..7]

type HasWindows: boolean

type AllLocked: boolean

type Granted: boolean

enum DoorPosition {
  CLOSED = 0
  OPEN = 1
  AJAR = 2
}

enum LockState {
  LOCKED = 0
  UNLOCKED = 1
}

enum LightState {
  OFF = 0
  ON = 1
  FLASH = 2
}

struct DoorState {
  position: DoorPosition
  locked: LockState
  sensorId: DoorIndex
}

struct WindowState {
  position: Ratio
  sensorId: DoorIndex
}

struct DoorSet {
  doors: [DoorState; 1..8]
}

struct WindowSet {
  windows: [WindowState; 1..8]
}

struct ClimateState {
  interiorTemp: Temperature
  targetTemp: Temperature
  fanSpeed: Ratio
  acActive: boolean
}

/// `timestamp` records when access was attempted — domain time, not the
/// envelope's publication time (RIDL-406 note).
struct AccessEvent {
  zone: Zone
  granted: Granted
  method: Label
  timestamp: Timestamp
}

/// Body control module interface.
/// Covers doors, windows, lights and climate.
///
/// @labels SIL_1, SEC_3, PRIVATE
interface BodyControl {
  signal doorStates: DoorSet @[50ms..2s]
  signal windowStates: WindowSet @[100ms..5s]
  signal climateState: ClimateState @[500ms..10s]

  event doorStateChanged: DoorState @[50ms..10s]

  /// Vehicle access attempt — elevated privacy.
  /// @labels SIL_1, SEC_4, CONFIDENTIAL
  event accessAttempt: AccessEvent @[100ms..30s]

  command setAllLocks(lock: LockState) @[..100ms]
  command setDoorLock(sensorId: DoorIndex, lock: LockState) @[..100ms]
  command setWindowPosition(sensorId: DoorIndex, position: Ratio) @[..100ms]
  command setClimateTarget(temp: Temperature) @[..100ms] [
    require temp >= 16.0
    require temp <= 30.0
  ]

  query getLockStatus(): (allLocked: AllLocked, unlockedCount: UnlockCount) @[..50ms]
  query getBodyStatus(): (doors: DoorSet, windows: WindowSet) @[..50ms]

  fixed doorCount: DoorCount
  fixed windowCount: WindowCount
  fixed hasElectricWindows: HasWindows
}

Annex 4 — Driver monitoring

DriverMonitoring draws RIDL-414 (low-cohesion-interface): its members fall into seven groups that share no named type, which the annex keeps to show one interface per subsystem.

package veh.dms

type Ratio: % [0.0..100.0 step 0.1]

type SampleInterval: integer [50..1000]

type ZoneCount: integer [1..16]

type Distracted: boolean

type Fatigued: boolean

type Monitoring: boolean

enum AlertLevel {
  NONE = 0
  LOW = 1
  MEDIUM = 2
  HIGH = 3
  CRITICAL = 4
}

enum GazeZone {
  FORWARD = 0
  MIRROR_LEFT = 1
  MIRROR_RIGHT = 2
  MIRROR_REAR = 3
  INSTRUMENT = 4
  INFOTAINMENT = 5
  OFFROAD = 6
  UNKNOWN = 7
}

struct AttentionMetrics {
  gazeZone: GazeZone
  eyeOpenness: Ratio
  headPitch: float [-30.0..30.0 step 0.1]
  headYaw: float [-90.0..90.0 step 0.1]
  attentionScore: Ratio
}

struct DrowsinessState {
  level: AlertLevel
  score: Ratio
  eyeClosurePct: Ratio
}

/// `timestamp` records when the distraction occurred — domain time
/// (RIDL-406 note).
struct DistractionEvent {
  level: AlertLevel
  gazeZone: GazeZone
  duration: Duration
  timestamp: Timestamp
}

/// `timestamp` records when the fatigue was detected — domain time
/// (RIDL-406 note).
struct FatigueEvent {
  level: AlertLevel
  score: Ratio
  timestamp: Timestamp
}

/// Driver monitoring system interface.
/// Processes biometric and behavioural signals to assess driver state.
///
/// @labels SIL_2, SEC_3, CONFIDENTIAL
interface DriverMonitoring {
  signal attentionMetrics: AttentionMetrics @[100ms..500ms]
  signal drowsinessState: DrowsinessState @[500ms..5s]

  event distractionDetected: DistractionEvent @[200ms..10s]
  event fatigueDetected: FatigueEvent @[500ms..30s]

  command acknowledgeAlert(level: AlertLevel) @[..50ms]
  command setMonitoringEnabled(enabled: Monitoring) @[..50ms]

  query getDriverState(): (
    attentionScore: Ratio,
    drowsinessLevel: AlertLevel,
    isDistracted: Distracted,
    isFatigued: Fatigued
  ) @[..100ms] [
    ensure result.attentionScore >= 0.0
    ensure result.attentionScore <= 100.0
  ]

  query streamAttention(interval: SampleInterval): <AttentionMetrics> @[..1s]

  fixed modelVersion: Version
  fixed sensorType: Label
  fixed gazeZoneCount: ZoneCount
}

Describing a system

Getting started declares contracts: the types a system carries and the interactions it offers. This chapter declares what uses them — which components exist, which contracts each one offers and requires, how the copies are bundled, and which machine each copy runs on. That is rsdl, the architecture layer of the family, and the rsdl reference is its specification.

What is built. The compiler reads .rsdl files, checks every rule of the reference, and lowers the checked system to the IR beside the package IR. ridl diff compares two systems.

What is not built. No runtime reads the lowered system. The links, the routing table and the grants this chapter shows are facts the compiler writes down; nothing delivers a message along them. No descriptor is emitted from the lowered system, and there is no transport.

Contracts first

rsdl declares no type, no interface and no service. An .rsdl file that tries draws RSDL-604. The contracts live in a ridl package, exactly as the getting started chapter writes them:

package veh.climate

type Temperature: integer [-40..85]

type FanLevel: integer [0..7]

type Heated: boolean

interface Climate {
  signal cabinTemperature: Temperature @[100ms..1s]
  command setFan(level: FanLevel) @[..50ms]
}

interface Seats {
  signal heated: Heated @[100ms..1s]
}

service veh.climate.control: Climate

service veh.climate.seats: Seats

service veh.climate.diag {
  query readTemperature(): Temperature @[..100ms]
}

veh.climate.diag declares its contract inline rather than naming a reusable interface, so its dotted name is also the name of its one interface.

Components

A component is one execution context. It offers services, requires interfaces, and names one reference per line:

package veh.cabin
import veh.climate.Climate
import veh.climate.Seats

/// Runs the climate loop. Two copies, one per zone controller.
component ClimateControl [ instances = (front, rear) ] {
  offers veh.climate.control
  requires Seats
}

component SeatHeating {
  offers veh.climate.seats
}

component Dashboard {
  requires Climate
  requires Seats
}

/// The phone app. No implementation in this workspace.
component PhoneApp [ external ] {
  requires Climate
  requires veh.climate.diag
}

• requires names an interface, never a provider. The compiler finds the one service in the closure that lists that interface, and the one component that offers that service. A consumer that requires the narrowest interface it needs is unaffected when the service gains or splits interfaces.
• instances names the copies. A component that declares none has one instance, written Unit in the IR and in diagnostics.
• external marks a component with no implementation in this workspace. It is still part of the closure, and its links are still derived.
• ClimateControl has two instances, so it is a redundant provider set. Dashboard's and PhoneApp's requires Climate each draw RSDL-409, "not yet realizable": every link is lowered to each instance, and there is no arbitration. The fence above allows RSDL-409 for that reason.

The system

A system is the closure — the components the build is about. A workspace declares at most one:

package veh.cabin

system Cabin {
  ClimateControl
  SeatHeating
  Dashboard
  PhoneApp
  veh.climate.diag
}

veh.climate.diag is a lone service that no declared component offers, so it stands for an implicit component of that name, with one Unit instance. Writing a component for it would say nothing the service does not already say.

Distributions

A distribution is what is versioned, signed and shipped together. When a workspace declares one, every implemented closure component is in exactly one:

package veh.cabin

distribution Comfort [ tier = PLATFORM ] {
  ClimateControl
  SeatHeating
  veh.climate.diag
}

distribution Display [ tier = APPLICATION ] {
  Dashboard
}

PhoneApp is external, so it is in no distribution. Display depends on Comfort, because Dashboard requires interfaces that ClimateControl and SeatHeating offer. The dependency is derived, never written. An application distribution may depend on a platform one; the reverse is a tier inversion, RSDL-901.

Deployments and machines

A deployment places the closure on machines. Each machine lists what it hosts, and every instance sits on exactly one machine per deployment:

package veh.cabin

deployment Car for Cabin {
  machine ZoneFront [ labels = (ASIL_A) ] {
    ClimateControl.front
    SeatHeating
    veh.climate.diag
  }
  machine ZoneRear {
    ClimateControl.rear
  }
  machine Head {
    Dashboard [ linux.cpuset = (1), slots = 8 ]
  }
  machine Cloud [ external ] {
    PhoneApp
  }
}

deployment Bench for Cabin {
  machine Rig {
    ClimateControl
    SeatHeating
    Dashboard
    veh.climate.diag
    PhoneApp
  }
}

• A bare component name places every instance of it, as Rig does with ClimateControl. ClimateControl.front places one.
• An external machine hosts external components only (RSDL-707). On Rig, PhoneApp is placed on an on-board machine: a stub standing in for the phone.
• linux.cpuset is a backend key, carried uninterpreted on Dashboard's placement. No configured backend claims the namespace linux, so it draws RSDL-804, which the fence allows.
• slots is a sizing key, written on a placement line like Dashboard's. It sets the table entries of every command or query channel that Dashboard consumes, in Car only. depth and budget are the other two, and a placement line and a deployment declaration both take all three; the reference gives their ranges and the precedence (rsdl reference §5).

Two mistakes are worth naming, because each blocks only its own deployment. Placing ClimateControl.front on ZoneFront and then reaching ClimateControl.rear twice in Car is RSDL-706, an instance placed twice. Dropping the ZoneRear machine leaves ClimateControl.rear on no machine, which is RSDL-701. Either one leaves the other deployment's lowering intact.

What the compiler writes

ridl check reports every rule above. ridl build writes the package IR and the lowered system beside it:

ridl build --emit ir-json --out-dir out && ls out

veh.cabin.Cabin.system.json
veh.cabin.ir.json
veh.climate.ir.json

The system artifact is named after the system's qualified name. --emit ir-text and --emit ir-binary write .system.txtpb and .system.binpb instead.

The facts inside it are stated once for the closure and once per deployment. For the closure:

• The components, with their instances, their offers and requires lines, and their external flag.
• The producers — for each service, the component that offers it and that component's instances. veh.climate.control is marked not yet realizable, because ClimateControl has more than one instance.
• The grants — per component, the catalog regions its requirements reach. PhoneApp reaches veh.climate, and its grant is lowered with the external flag: it is derived here, and enforcing it is the external side's business. SeatHeating requires nothing, so its grant is empty.
• The region map — one region per catalog the closure reaches, here veh.climate, holding Climate, Seats and veh.climate.diag with the number each takes from the unit's interfaces.lock. A region is one per unit, and the interface names in a region, like those in a route, are catalog names: the name relative to the unit, such as Climate for an interface of the unit's root package or cluster.Speed for one of a subpackage. An inline shape keeps its global name, so veh.climate.diag appears under that name. Each region also carries the catalog hash, computed by ridl over the unit's interfaces, their numbers and every type they reach: the same hash --emit catalog writes in the unit's descriptor.
• The distributions, with the derived dependency.

Per deployment:

• The placements — every instance with the machine it runs on, including an instance with no link at all.
• The links, one per consumer instance and producer instance, each with its crossing kind. In Car, ClimateControl.front → SeatHeating.Unit is same machine, ClimateControl.rear → SeatHeating.Unit is different machine, and every link from PhoneApp is off-board. In Bench every link is same machine, because everything sits on Rig.
• The routing table — the key (catalog, interface number, member ordinal) to the producing instances and their machines, for every member of every interface a closure service lists.
• The surface set — the system's external boundary. Here it is the three links from PhoneApp, with the external side consuming, in both deployments: the external flag and not the machine defines the boundary, so Bench keeps them although they cross nothing.
• The installation of each distribution — in Car, Comfort on ZoneFront and ZoneRear, Display on Head.

What an error does. An error in the closure blocks the lowering of every deployment, and the build writes nothing. An RSDL-7xx error — a placement problem, or a sizing value out of range (RSDL-709) — blocks its own deployment only: the build writes the package IR and the system without that deployment, and still exits 1.

Comparing two systems

ridl diff compares the contracts by the ridl categories, and those alone give the verdict and the exit code. The changes that are not contract changes are listed after them, under two headings and with no verdict. Moving Dashboard from Head to ZoneRear in Car:

identical
placement changed
  Car/veh.cabin.Dashboard.Unit: Head -> ZoneRear

The contracts did not move, so the verdict is identical and the exit code 0. A requires line added, a component added to the system, instances changed, a component made external, or a component moved from one distribution to another are listed under composition changed instead. A changed labels, deprecated, tier or backend key is listed under the heading of the declaration it is on, as a before-and-after line; a changed sizing key (depth, slots, budget) is not listed, because it changes no link and no contract. Which of these changes break an already deployed system, and for whom, is not something the compiler decides.

What is not here yet

• No runtime reads the lowered system, and no descriptor is emitted from it. The facts are written down and go no further.
• rsdl declares no transport, no network and no process. A same-machine crossing says two instances share a machine, not how they talk. If a backend needs such a fact, it arrives as that backend's namespaced key.
• Posture, redundancy arbitration and the optional requirement are reserved — see §12 of the reference. A redundant provider set is reported, not resolved.

Remote units and ridl vendor

A package does not have to live in your repository. This chapter shows how to import a package from a URL, where the compiler reads it from, what ridl.lock pins, how ridl vendor copies it into your repository, and how to build with no network. The CLI reference lists what each command writes, and ADR-0002 records the rules; this chapter is the guide.

The examples use TOML manifests and shell sessions. A remote import needs a network, so no block here is compiled, and the URLs are placeholders.

Import a package from a URL

The [imports] table of a manifest names each remote package. The key is the package name that the remote package declares in its own ridl.toml; the value is the URL of a tar archive that holds the package:

[package]
name = "veh.cluster"

[imports]
"veh.common" = "https://registry.example.com/veh/common@v1.0.0"

A package that is a member of a workspace puts its imports in the root manifest or in its own manifest. The compiler takes the union of both.

In a source file, import from the remote package as from any other package:

import veh.common.Speed

The import resolves by the longest dot-separated prefix that is an [imports] key, so veh.common.Speed finds the key veh.common. A remote package exposes the same declarations to you as a package in your repository does, except internal ones.

A remote package, called a remote unit in the diagnostics, follows these rules:

• Its archive holds one package at the top level: a ridl.toml with a [package] table, not a [workspace] table, whose name equals the [imports] key. Anything else is MANI-105.
• Your [imports] lists every remote package the build needs, including the ones that your remote packages import. The compiler does not fetch the imports of a remote unit. It reads them only to check that you list each key, and a key you do not list is MANI-106, with a message that names the URL the remote unit gave. When the two URLs differ, yours is used.
• A remote unit is a read-only dependency. Its errors fail the command, its warnings and infos are not shown, and your [lints] table does not apply to it. ridl build generates code for it beside your own packages, and ridl fmt never changes it. No catalog, baseline snapshot or ridl lock entry includes it; its owner publishes those.
• The compiler skips the entries that macOS adds to an archive when it reads a remote unit: any file or directory whose name starts with ._, and the __MACOSX/ directory. Your own packages are read as they are.

Where the compiler reads a remote unit from

For each URL, the compiler takes the first source that applies:

1. vendor/<key>/ at the manifest root, when that directory exists and ridl.lock pins a tree for the URL.
2. The cache, ~/.ridl/cache, for the hash that ridl.lock pins.
3. A fetch from the URL, which stores the archive in the cache. Only commands that may fetch do this, and never under --frozen.

When ridl.lock pins no tree for the URL, the compiler reads the cache or fetches first, so that a pin exists. It then verifies a vendored directory, if there is one, against that pin and reads the directory in place of the cache entry.

Which commands fetch and which only read matters:

The ridl check section of the CLI reference says when a run writes ridl.lock.

What ridl.lock pins

ridl.lock sits at the manifest root, beside ridl.toml. Each remote import has one entry, keyed by its URL:

[entries."https://registry.example.com/veh/common@v1.0.0"]
sha256 = "<the SHA-256 of the fetched archive>"
tree = "<the hash of the unpacked tree>"

• sha256 pins the bytes of the downloaded archive. A fetch whose content hashes to another value is MANI-102, and the import is dropped.
• tree pins the unpacked tree: a SHA-256 over every regular file in it, with its path and length. It is what the compiler checks on a cache entry and on a vendored directory. A tree that does not match is MANI-107. A tree that holds a symbolic link or another file that is not a regular file is also MANI-107, and the message names the file.

Commit ridl.lock. It is generated: do not edit it by hand. A ridl.lock written before the tree hash existed has no tree. A run without --frozen adds it. A run with --frozen, and ridl vendor --check, report MANI-108 instead, because they never write.

Copy the units into the repository with ridl vendor

Run the command from any directory of the project:

$ ridl vendor
vendored veh.common

The command acts on the manifest root above the directory, so vendor/ is at the workspace root whichever member you run it from. It copies each remote unit of your [imports] to vendor/<key>/ and updates ridl.lock. It also removes the directories in vendor/ that no [imports] key names. The ridl vendor section of the CLI reference gives the exact rules for what the command writes, removes and leaves alone.

Commit vendor/ together with ridl.lock. The tree hash covers the bytes of every file, so keep Git from converting line endings in vendor/; the CLI reference gives the .gitattributes line.

After a change of URL in [imports], run ridl vendor again to replace the directory.

Check the directory in CI

ridl vendor --check compares vendor/ with the imports and with ridl.lock. It fetches nothing and writes nothing, so it suits CI:

$ ridl vendor --check

It exits 0 when vendor/ matches. A failure reports MANI-109, MANI-110, MANI-107, MANI-103 or MANI-108; the CLI reference gives the meaning of each and the exit codes. In each case, run ridl vendor and commit the result.

Build with no network

An air-gapped build needs the units in the repository. On a machine with a network:

$ ridl vendor
$ git add ridl.lock vendor
$ git commit -m "chore(deps): vendor the remote units"

On the machine with no network, and no cache:

$ ridl check --frozen

Under --frozen, the compiler reads vendor/<key>/ first, verifies it against the tree in ridl.lock, and fetches nothing. The same holds for ridl build --frozen.

A project that does not vendor can still build offline, as long as the cache holds every pin: ridl check --frozen reports MANI-103 for a URL with no ridl.lock entry and MANI-104 for a pinned unit that is not in the cache. The message of MANI-104 names ridl check and ridl vendor as the fix.

Fresh clones

ridl test, ridl lock, ridl diff, ridl lsp and ridl mcp never fetch and never write ridl.lock. In a fresh clone of a project that imports remote units and does not commit vendor/, the cache is empty, so run ridl check once first. It fetches the units into the cache and writes ridl.lock. Otherwise these commands report MANI-103 or MANI-104. A project that commits vendor/ and ridl.lock needs no such step.

The vendor/ directory is reserved

vendor/ at the manifest root belongs to ridl vendor. The loader does not read source files there as packages of your project:

• In a workspace, a members entry that is vendor or a path under it is MANI-017, an error, and the entry is not loaded.
• In a standalone package, a .typl, .ridl or .rsdl file under vendor/ that is not inside a directory named by an [imports] key is MANI-018, a warning with the lint name vendor-source-not-loaded, and is not loaded. One warning is reported per file.
• The name is reserved at the manifest root only. A directory named vendor deeper in a package is an ordinary source package. A remote unit's own vendor/ directory is part of its tree and its hash, and the compiler skips it when it reads the unit.

This is a breaking change for a project that kept source packages in a vendor/ directory at its root. Those packages stop loading. Move them to another directory, and update the members list of the workspace or the imports that name them.

ridl fmt also skips vendor/ at every manifest root, so it does not rewrite the units that belong to other owners.

Where to go next

• Getting started shows the workspace that a remote import joins.
• The ridl check and ridl vendor sections of the CLI reference list the exit codes.
• The lints page lists vendor-source-not-loaded.
• ADR-0002 records the module system, the lockfile and the vendor directory.

Using the generated Rust code

ridl build --emit rust turns a package into a Rust crate. This chapter shows how an application uses that crate: the types it holds, the two ways to call an interface — async and blocking — the Cargo features that select what the crate contains, and the failures a call can report. The flag itself is described in the CLI reference.

Most code snippets in this chapter are taken from examples/cabin/consumer/src/main.rs, a program that the repository's just demo gate builds and runs against the crate generated from examples/cabin/cabin.ridl. A snippet that is taken neither from that program nor from that schema is marked as an illustration in the sentence before it, and is not compiled. The interface the snippets call, and the types it uses, from that schema:

package veh.cabin

/// Cabin air temperature, in degrees.
type Temperature: integer [-40..85]

/// A percentage of full scale.
type Level: integer [0..100]

/// An averaging window, in milliseconds.
type Window: integer [0..100000]

/// The average a query replies with. Its range is wider than `Level`'s,
/// so a reply is not constrained to the scale the command takes.
type Average: integer [0..1000]

/// The health of a cabin subsystem.
enum Health {
  /// The subsystem works normally.
  OK = 0
  /// The subsystem works, with a fault that needs attention.
  WARN = 1
  /// The subsystem does not work.
  FAIL = 2
}

/// Raised when a subsystem leaves `OK`.
struct Warning {
  /// The warning code, as a percentage of full scale.
  code: Level
  /// The health the subsystem moved to.
  health: Health
}

/// The cabin's own interface: a signal, an event, a command and a query, so
/// the proof covers every interaction kind that carries a payload.
interface Cabin {
  /// The current cabin air temperature.
  signal temperature: Temperature @10ms
  /// Sent when a subsystem leaves `OK`.
  event warning: Warning @[100ms..1s]
  /// Sets the cabin level, below 100.
  command setLevel(level: Level) @[..50ms] [
    require level < 100
  ]
  /// The average level over the window, in milliseconds.
  query average(window: Window): Average @[..200ms] [
    require window > 0
    ensure result >= 0
  ]
}

What the crate contains

The build writes one <package>.rs file per package, a lib.rs that declares the module tree, and a Cargo.toml. A package veh.cabin is the module veh::cabin. The crate is named after the [package] name of the ridl.toml manifest, with each . replaced by _: examples/cabin declares the package veh.cabin, so its crate is veh_cabin. A [workspace] manifest names no package, and a build from one names the crate ridl_generated.

The cabin program imports the package module as api, the face of the interface Cabin as cabin, and the face's prelude:

use api::cabin;
use api::cabin::prelude::*;
use ridl_loopback::Loopback;
use ridl_rt::contract::{CatalogRef, Interface};
use ridl_rt::encoding::Podbuf;
use ridl_rt::payload::{Payload, Ref};
use ridl_rt::sample::Provenance;
use veh_cabin::veh::cabin as api;

prelude brings into scope the traits that carry the fixed methods of the face: ridl_rt::face::Bind (new), Events (next_event), Publish (commit), and, under the crate's std feature, Timeout (with_timeout and set_timeout); and, without a name, the interface's own Subscribe (subscribe_<event>) and Invalidate (invalidate_<signal>) traits. Each interface's prelude holds only the traits its face implements. These methods are trait methods rather than inherent methods so that a member of the interface can have one of these names. Without the use of the prelude, cabin::Client::new does not compile. The other imports are for the snippets below: Loopback is the runtime, CatalogRef and Interface name the catalog the face was generated from, and Provenance is read from a signal sample. A Loopback carries FlatBuffers, which is its default encoding; the face takes the encoding from the port it is bound to and names none itself.

The package module holds:

• The domain types. A struct, an enum, an enum set, a union and a named scalar each become a Rust type. A constrained type is built with new, which checks the typl constraints and returns an error when the value breaks one; new_unchecked skips the check and is for a value already known to satisfy them. get returns the value of a named scalar.
• The codecs of each payload type, one per encoding the manifest names under [backend.rust] encodings: flatbuffers, proto3, or both. Each codec is encode, verify, decode and a MAX_SIZE bound; with no list the module holds the types only. Each payload type also has a <T as Payload<FlatBuffers>>::Buffer type and a zeroed BUFFER value, sized by that type's own MAX_SIZE, and the same in Proto3. Every MAX_SIZE is finite: a declared type whose encoding has no finite bound, such as a string with no length bound, is refused in either encoding, and ridl build fails with an error that names the type and the cause; the proto3 codec record's known gaps give the limit this sets and its tracking issue. The face calls the codec; an application calls it only when it moves payloads by itself.
• The interaction descriptors: one unit type per interface (here api::Cabin) that implements ridl_rt::contract::Interface and carries the interface's CATALOG, NUMBER and NAME. Each interface also implements ridl_rt::contract::Sizes<E> for each encoding the package carries, the size table of that codec for the interface: its reservations, its largest buffer (MAX_BUFFER_SIZE), and the claim and event buffers the face holds. Like the codecs, the descriptors are present only when the manifest names an encoding under [backend.rust] encodings.
• The face: one module per interface that has one, named after it (here api::cabin), present under the same condition. The face is what the application calls.

The face

Each interface module holds the parts its own interactions need:

An interface that carries only fixed declarations gets no face module, and neither does an internal interface, whose descriptors are crate-visible (the design record gives the reason). A signal-only interface gets a Client and a Publisher and no blocking module, because a signal read returns at once.

An interface the face cannot carry gets none of these items and no interaction descriptor. In their place, the package module holds a __RIDL_NO_FACE_<NAME> constant whose documentation names the interface and the reason; the CLI reference lists the cases.

A call always sends one named type. A command or query with exactly one parameter of a named type sends that type. Any other parameter list gets an argument struct that the compiler names <Interface><Call>Params, with one field per parameter in declaration order, each carrying the parameter's documentation. A call with no parameter sends the same kind of struct with no field. A query whose reply is a tuple, or that declares no return type, gets a reply struct named <Interface><Call>Reply in the same way. These structs are generated types of the package module, and the face methods take and return them like any other payload. The wire backends emit the matching positional .proto messages and .fbs tables under the names assigned by lowering. When an induced payload has no finite bound in an encoding the manifest names — no finite FlatBuffers bound under flatbuffers; no finite proto3 bound, or a member proto3 cannot represent, under proto3 — its interface is skipped with the refusal constant described above rather than emitting a descriptor that names a missing codec.

The face opens no socket and holds no runtime. Each Client, Publisher and serve runs over a port that the application passes in, and a port comes from a runtime. The one runtime in this repository is ridl-loopback, which connects the faces of one process to each other. The cabin program binds every face to it:

    let rt = Loopback::new(CATALOG);
    let mut publisher = cabin::Publisher::new(rt.attach());
    let mut client = cabin::Client::new(rt.attach());
    let mut blocking_client =
        cabin::blocking::Client::new(rt.attach()).with_timeout(CLIENT_TIMEOUT);
    let mut handler = rt.handler();
    let mut provider = Cabin {
        levels: Vec::new(),
        average: api::Average::new(7).expect("7 is inside Average's range"),
    };

CATALOG is a constant of the program that holds the catalog the face was generated from, read from <api::Cabin as Interface>::CATALOG. Binding a face compares the port's catalog with it, and panics when they differ; see Failures. CLIENT_TIMEOUT is a Duration the program declares, and with_timeout comes from the Timeout trait of the prelude.

Implementing the provider

The application implements one method per command and per query. A command's method returns nothing, and a query's method returns the reply type:

struct Cabin {
    levels: Vec<i64>,
    average: api::Average,
}

impl cabin::Provider for Cabin {
    fn set_level(&mut self, level: &api::Level) {
        self.levels.push(level.get());
    }
    fn average(&mut self, _window: &api::Window) -> api::Average {
        self.average
    }
}

The method is called only with a request that passed every check: the payload verified, its typl constraints hold, and its require clauses are true. For a query, serve evaluates the ensure clauses on the reply before it sends it. The provider does not repeat those checks.

Async calls

The Client methods for a command and a query, next_event, and serve each return a named future. The futures are executor-agnostic: they take no dependency on an async runtime, and any executor can poll them. A call is sent when the method runs, not when its future is first polled.

Inside an async function, the calls read like this. This snippet is an illustration and is not compiled; port and handler stand for ports a runtime gives the application, and provider for a value that implements cabin::Provider:

// Illustration: any executor polls these futures.
let mut client = cabin::Client::new(port);
client.set_level(api::Level::new(42).expect("in range")).await?;
let average = client.average(api::Window::new(10).expect("in range")).await?;

// On the provider side, `serve` settles calls until the handler port fails.
// Its output is `Result<Infallible, ProviderError>`: it never resolves to `Ok`.
let failure = cabin::serve(handler, &mut provider).await;

No executor is required either. The cabin program polls the same futures by hand, the way a frame loop does. cx is a Context built from the waker ridl_rt::task::noop_waker(), and poll_once is a function of the program that polls a future once with it:

    {
        let mut serve = cabin::serve(&mut handler, &mut provider);
        let mut call = client.set_level(api::Level::new(42).expect("42 is inside Level's range"));
        // Step 1: the call was sent when `set_level` ran, and nothing has
        // served it yet.
        assert!(poll_once(&mut call, &mut cx).is_pending());
        // Step 2: one pass of the provider side settles it.
        assert!(poll_once(&mut serve, &mut cx).is_pending());
        // Step 3: the acknowledgment is taken.
        assert_eq!(poll_once(&mut call, &mut cx), Poll::Ready(Ok(())));
    }

ridl_rt::task exists only under ridl-rt's std feature, which the generated crate's own std feature turns on. A frame loop built without it uses core::task::Waker::noop() instead, which Rust 1.85 and later provide.

A serve future settles at most 32 calls in one poll. When it reaches that limit, it wakes its own waker and returns Pending, so that an executor can run other tasks before it polls the serve future again. Under noop_waker that wake is lost, so a frame loop that polls once per frame settles at most 32 calls per frame.

The future of a command or a query call, and the serve future, panic when they are polled again after they resolved. The next_event future does not: polled again, it waits for the next occurrence.

Blocking calls

The blocking module holds the same Client and serve for code that waits on a thread instead of polling. Each blocking call is ridl_rt::task::block_on over the async call, so the two forms cannot differ in what a call does; the blocking form only adds the wait and a timeout.

A blocking client takes its timeout with with_timeout (or set_timeout). The default is no timeout. A call returns its outcome, or the timeout result when the timeout passes first. A signal read and a subscribe_* call return at once, as in the async client.

Blocking serve takes the handler, the provider and an optional timeout. It returns Ok(()) when the timeout passes, so a thread that also does other work can call it in a loop. SERVE_PASS is a Duration of 50 ms the program declares:

/// Serves `provider` over `handler` on the calling thread until `done` is
/// set: `blocking::serve` returns `Ok(())` at each pass's timeout, and the
/// loop calls it again. A failure of the handler port ends the loop with it.
fn serve_until_done(
    handler: &mut ridl_loopback::HandlerHandle,
    provider: &mut Cabin,
    done: &AtomicBool,
) -> Result<(), ridl_rt::error::ProviderError> {
    while !done.load(Ordering::Acquire) {
        cabin::blocking::serve(&mut *handler, &mut *provider, Some(SERVE_PASS))?;
    }
    Ok(())
}

The cabin program runs that loop on a second thread and calls the blocking client on the first. DoneOnDrop is a type of the program that sets done when it is dropped, so that the serving loop also ends when the first thread panics:

    let done = AtomicBool::new(false);
    let served = std::thread::scope(|scope| {
        let serving = scope.spawn(|| serve_until_done(&mut handler, &mut provider, &done));
        let _ends_the_loop = DoneOnDrop(&done);
        let acknowledged =
            blocking_client.set_level(api::Level::new(43).expect("43 is inside Level's range"));
        done.store(true, Ordering::Release);
        assert_eq!(acknowledged, Ok(()));
        serving.join().expect("the serving thread does not panic")
    });

With no timeout, a blocking call returns only with its outcome, blocking next_event only with an event or a read failure, and blocking serve only with a failure. At the timeout, blocking next_event returns Ok(None).

Converting a payload between encodings

With [backend.rust] transcode = true in the manifest, the generated crate carries one function for each ordered pair of distinct encodings that [backend.rust] encodings lists, on each payload type that has a Payload implementation under both. The manifest must list at least two encodings.

[backend.rust]
encodings = ["flatbuffers", "proto3"]
transcode = true

The function is named transcode_<s>_to_<d>, where <s> is the source encoding and <d> the target, spelled as in the manifest with - replaced by _. For a type Speed the crate holds:

impl Speed {
    pub fn transcode_flatbuffers_to_proto3<'o>(
        bytes: &[u8],
        out: &'o mut [u8],
    ) -> Result<
        ridl_rt::payload::Ref<'o, Self, ridl_rt::encoding::Proto3>,
        ridl_rt::payload::TranscodeError,
    >;
    pub fn transcode_proto3_to_flatbuffers<'o>(/* the same parameters */)
        -> Result</* a Ref in the FlatBuffers encoding */, /* the same error */>;
}

The function verifies bytes under the source encoding, decodes the value, and encodes it under the target encoding into out. It calls ridl_rt::payload::transcode, which allocates no buffer of its own; the type's decode may allocate, as for a string field. An out that is too small is TranscodeError::Encode with EncodeError::Capacity, and bytes that do not verify are TranscodeError::Verify. A function exists only where the type has a Payload implementation under both encodings of the pair.

A podbuf buffer starts on an 8-byte boundary. A caller passes an out for a podbuf target, and bytes for a podbuf source, that starts on one: the type's <T as Payload<Podbuf>>::BUFFER is an Aligned array, and ridl_rt::podbuf::Aligned wraps any other array. An out that is not aligned is EncodeError::Unaligned, and bytes that are not aligned do not verify. A map is written in key order, so a value whose map is in another order decodes from a podbuf source in key order.

Cargo features

The generated Cargo.toml declares two features, both on by default:

With std and validate-pattern both off, the generated crate and ridl-rt are both no_std and build for a target that has no standard library. Its lib.rs declares this with #![cfg_attr(not(any(feature = "std", feature = "validate-pattern")), no_std)]. The crate still needs an allocator: under the same condition its lib.rs links alloc under the name std (extern crate alloc as std;), because the package files name ::std::string::String and ::std::vec::Vec for strings, bytes, arrays and maps. Single-file mode writes no lib.rs, so the crate that includes the file decides. A crate that is always no_std declares extern crate alloc as std; in its own root. A crate that is no_std only under a condition declares it under the same condition: where the alias is declared, ::std names alloc, so a path that only the standard library has, such as ::std::sync::LazyLock, no longer resolves.

A target where regex is too large, or one that does not need the blocking face, turns the defaults off and selects what it needs. This Cargo.toml fragment is an illustration and is not compiled:

[dependencies]
veh_cabin = { path = "generated", default-features = false }

The generated crate depends on ridl-rt with one feature per encoding that the manifest names under [backend.rust] encodings — flatbuffers, proto3, podbuf, or a combination, which the codecs need — and no feature for a types-only build. An application that names ridl-rt itself, for example to use ridl_rt::task::noop_waker or the error types, selects from its features:

ridl-rt has no dependency in any feature combination. It builds for wasm32, and its minimum Rust version is 1.88. The generated crate declares edition 2021 and rust-version = "1.88", and builds with Rust 1.88 or later with every cargo feature on or with default features off. To keep Rust 1.88, resolve its dependencies as Stability describes. When you build the generated crate as its own workspace root, its edition 2021 selects resolver 2, which by default does not read rust-version. Resolve with CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback; cargo then selects the dependency releases that Rust 1.88, the manifest's rust-version, supports, as just compat-check does.

The wasm-exports feature

With [backend.rust] wasm = true in the manifest, or codec = true on another backend table, which implies it, the generated Cargo.toml declares a third feature, wasm-exports, off by default, which turns std on. It compiles the exports of the crate's wasm module when the target is wasm32, and nothing on any other target. The manifest declares no crate type, so a Rust program that depends on the crate links no export. The WebAssembly module is built from the crate's directory with:

CARGO_PROFILE_RELEASE_OPT_LEVEL=z CARGO_PROFILE_RELEASE_LTO=true \
CARGO_PROFILE_RELEASE_PANIC=abort \
cargo rustc --release --target wasm32-unknown-unknown --crate-type cdylib \
  --features wasm-exports

The module exports ridl_alloc, ridl_free, ridl_catalog_hash, ridl_verify and ridl_type_id. ridl_type_id returns the type id of a payload type named by its qualified name. It returns -1 for a name the list does not hold, an empty name, bytes that are not UTF-8, a null pointer with a length, a length above isize::MAX, and a pointer and length whose sum overflows the address space. A range past the end of the module's memory traps, as any read past it does.

The three variables are the recommended size settings, and cargo reads them from the environment. The module is target/wasm32-unknown-unknown/release/<crate name>.wasm.

Failures

A call reports its failure as a value. ClientError, CallError, Contract, Transport and ProviderError are in ridl_rt::error; the port errors, such as SendError and ReadError, are in ridl_rt::port.

A command or query call resolves to Result<_, ClientError>:

• ClientError::Send — the call was not sent. A require clause that is false is reported here, as SendError::Contract(PreconditionFailed), because the client evaluates the require clauses before it sends anything.
• ClientError::Call — the call was sent, and its outcome is a failure. CallError::Contract is a contract error the provider side reported: InvalidValue (the payload breaks its typl constraints), PreconditionFailed, ContractBroken (an ensure clause is false) or UnknownInteraction (the peers disagree on an interface number or an ordinal). CallError::Transport is an infrastructure failure: Timeout, Undelivered, Down, Corrupt or Busy.
• ClientError::Read — the port failed while the reply was read.

When a call's max bound passes, a sent command resolves to Transport::Undelivered and a sent query to Transport::Timeout. The bound is measured on the port's clock, so it depends on the runtime. The clock of ridl-loopback moves only when the program calls Loopback::advance, so over it a bound passes only after the program advances the clock past it; until then, a call that is never served returns only at the blocking client's own timeout.

A signal read returns Result<Sample<T>, ReadError>. serve resolves to ProviderError::Serve when the handler refuses the interface's members, which it reports on the first poll, and to ProviderError::Claim when the handler port fails while a call is read. The calls it settled before a failure stay settled.

A catalog mismatch panics. Binding a Client or a Publisher, and starting serve, compare the port's catalog — the unit name and the catalog hash — with the CATALOG the face was generated from. When they differ, the face was generated from a different version of the unit than the one the runtime serves, and the bind panics with a message that names the interface and both catalogs. A program that must not panic compares the two itself before it binds. This snippet is an illustration and is not compiled; port stands for the port the program is about to bind:

use ridl_rt::contract::Interface; // carries `CATALOG`
use ridl_rt::port::Attached;      // carries `catalog()`

if port.catalog() != <api::Cabin as Interface>::CATALOG {
    // refuse the port
}

The catalog and its hash are described in The catalog descriptor.

TypeScript

ridl build --emit typescript writes the domain types of a package as one .ts file: branded scalars, interfaces, enums, enum sets, discriminated unions and init functions. It emits no face and no feature selection, so there is no async or blocking API to choose between.

With [backend.typescript] codec = true it also writes <base>.codec.ts, for every package that has a payload root with a codec (its own, or one of another package that its interfaces name): one encode<Name> and one decode<Name> function per payload type, which take and return the plain objects of <base>.ts and call the object API that flatc generates; one table per interface, which gives each interaction its interface number, its ordinal, its kind and the functions of its payloads; and the catalog's name and hash, the payload type names and the rule texts that the wasm codec takes at load. ridl does not run flatc. Build the files in two steps:

ridl build --emit typescript --emit flatbuffers --out-dir <out-dir>
flatc --ts --gen-object-api -o <out-dir> <out-dir>/<base>.fbs

The codec file imports flatc's output from ./<package path>.js (for veh.cabin, ./veh/cabin.js), so flatc's -o is the directory of the TypeScript files. When a payload type of an interaction is a named scalar or an enum set of another package (ridl.std.Name as the request of a query, for example), the codec file goes through that package's own codec file, <package>.codec.ts, which the build writes beside it; flatc then runs on that package's schema too, in the same directory:

flatc --ts --gen-object-api -o <out-dir> <out-dir>/<base>.fbs <out-dir>/<package>.fbs

A package with no such payload root, and ridl.std when no codec file imports its module, gets no codec file. The converters cover every typl kind: a union by its kind and value, a tuple by its named fields, an array, a map by its entries, an optional field (absent when the buffer leaves it out; an optional array, bytes or map field reads back as empty, because the object API cannot leave a vector out of the buffer), and an induced tuple of an interaction, which the codec file exports as an interface (export type X = Record<string, never> for one with no field). An optional array element, map key or map value is refused, as the Rust codec refuses it. A named scalar or an enum set of another package converts by a type assertion, and a payload type of another package that is one goes through that package's own codec file; a payload type that reaches a struct, a union or an enum of another package is refused with an error that names both. An internal payload type has no encode/decode, because <base>.ts does not export its type. The codec table design record gives the rules in full.

Documentation in the generated code

The doc comment of a declaration or a member (see Documenting your API) becomes the doc comment of the item generated from it: rustdoc in the Rust crate, TSDoc in the TypeScript module. The generated doc also lists the item's rules: the facts the schema states about the values the item admits and the way it is used. They are the same lines the editor's hover shows in its Contract list.

A generated doc holds these parts, in this order, and leaves out each part that is empty:

A link, or an @see target, whose target has no item in the same output is written as a code span of the target's qualified name, such as veh.common.Speed, so that no doc in the crate or the module that ridl build emits holds a link that does not resolve. Both backends link only to a declaration of the package itself or to a declaration of another package that this package reaches through a type. A target that this package does not reach through a type is written as a code span. In both languages, so is an internal declaration, a constant the backend does not emit (such as a bytes constant), and a member of a named scalar or of a constant, which has no member item. In Rust it is also the case for an event, a fixed, an interface with no face module, a target whose path Rust spells with a raw identifier (r#move), and an item whose name the module of a child package takes, which a program reaches only through the hidden __ridl_package module. In TypeScript it is also the case for an interface, an interaction and a union arm, which the module holds no item for, and for a declaration of another package that the module does not import. @labels is not rendered.

A Rust link uses the short form [Speed] when that text is the target's Rust name and the target is in the module that holds the doc. When a Markdown reference definition uses the same label, the generated shortcut uses code formatting to preserve the resolved target. Other links use an absolute path from the crate root, such as crate::veh::common::Speed, which resolves in the crate ridl build emits. A program that brings a generated file in with include! inside a module of its own moves the items away from those absolute paths, so rustdoc reports those links as unresolved.

In the Rust face, the doc of an interaction goes on these methods: for a signal, the method of the async Client, of the blocking Client and of the Publisher; for a command or a query, the method of the async Client, of the blocking Client and of the Provider trait; for an event, the subscribe_<event> method of the async and of the blocking Client, and the method of the Publisher. The Client and Provider methods also carry the interaction's #[deprecated]; a Publisher method and a subscribe_<event> method carry the doc without #[deprecated]. The variant of an event in the Event enum carries only a sentence the backend writes. A method's doc is the interaction's doc text, then a sentence the backend writes about the method itself, then the # Rules section, then, for a command or a query, a # Parameters section (one bullet per parameter with its name and its doc, and the parameter's rules as nested bullets), then the # See also section and the Available since lines. The doc of an interface goes on its face module, in the same order around the module's own sentence.

What the generated code checks

The rules lists state the contract, not what the code checks. On each item the backend emits, every rule the schema declares is listed, in the same words in both languages, whether or not the generated code checks it. The sentence the backend writes about a method describes what that method does, its checks included: the doc of a named scalar's new says that it returns an error for a value that breaks a constraint the generated code checks, the doc of a Client call method says what happens when a require clause fails, and the doc of a query's Provider method says that serve discards a reply that breaks an ensure clause.

This table records, for each kind of rule, the generated item that checks it:

In the Rust column:

• new and TryFrom are the constructors of a named scalar. verify is the FlatBuffers codec's check of a received payload. It also checks a field whose type is written inline, which has no constructor. encode also checks anonymous string and byte lengths and variable-length collection counts. Exact array counts are enforced by their Rust type. Other field constraints and map-key uniqueness are checked by verify.
• The pattern is checked only when the crate is built with the validate-pattern feature (see Cargo features).
• A call's future, in the async and in the blocking Client, resolves to a failure when the response bound's max passes (see Failures). Its min is not checked.
• A query that declares an error type gets no face, so no generated item carries the errors rule.
• A Client call method evaluates the require clauses before it sends. serve evaluates them before it calls the Provider, and evaluates the ensure clauses on the reply before it sends the reply. The Client does not evaluate ensure.
• verify and the face exist only when the manifest names flatbuffers or proto3 under [backend.rust] encodings (see What the crate contains).

The TypeScript module holds types, constants, the <Name>Bits objects and init functions only, and none of them checks a value.

An item that the generated code needs but a program does not name carries no doc. In Rust it is pub(crate), such as the constraint check behind new and the codec's functions for each table, or pub under #[doc(hidden)] where code outside the crate must reach it, such as the descriptor of each interaction, which a runtime reads. Two private Rust constants are notes rather than such items: __RIDL_NO_FACE_<NAME>, left where an interface's face was not emitted, and __RIDL_FB_NO_CODEC_<Name>, left where a declaration's FlatBuffers codec was not emitted. Each carries a doc that says what was not emitted and why, for a reader of the generated source; rustdoc does not show them.

Further reading

• The interaction face — the design record of everything the Rust backend emits for an interface.
• ridl-rt — the design record of the runtime library: its ports, features and error types.

Writing a port

This chapter is for the author of a runtime: a crate that implements the port traits of ridl-rt for a platform or a transport, so that a generated face can run over it. It names the traits by role, shows how to test an implementation with the published conformance suite, and lists what a runtime that carries frames over a transport must decide for itself. The exact signature of every trait is in the ridl_rt::port documentation.

The runtime and the face

A generated face holds no runtime. Each Client, Publisher and serve of the face runs over a value that implements some of the traits of ridl_rt::port, and calls only those traits; it never names the runtime that implements them (Using the generated Rust code). A runtime is a separate crate that implements those traits.

Three properties hold for every port method. It returns without waiting: a face that waits registers its interest with the runtime and reads the port again when the runtime wakes it. It names no payload type: it carries an interface number, an ordinal and bytes, and the generated code encodes and decodes. It takes no current time: the runtime reads its own clock.

A runtime exposes one handle type for each port trait it implements, and it may also offer an aggregate handle that implements every trait one interface's face needs. ridl-rt already implements every port trait for &mut P, and the traits whose methods all take &self also for &P, so a runtime does not write those implementations. No port trait has Send or Sync as a supertrait. A runtime whose handles are used from more than one thread makes a handle Send + Sync when all its traits take &self, and Send when one of them has a &mut self method, and checks this itself.

The port traits

Attached and Clock. Attached has one method, catalog, which returns the CatalogRef the port serves; every interaction port has it as a supertrait. Clock has one method, now. A runtime has one clock and stamps every envelope from it. Neither method returns an error.

Encoded. A port states the encoding of the bytes it carries through one associated type:

use ridl_rt::encoding::FlatBuffers;
use ridl_rt::port::Encoded;

impl Encoded for MyPort {
    type Encoding = FlatBuffers;
}

A generated face reads that encoding from the port it is bound to and names no encoding itself, so every port a face is bound to implements Encoded. It is not a supertrait of Attached: a port that never meets a face, such as a fixture for the conformance suite below, is not forced to name an encoding. One session carries one encoding, so a transport that serves several hands out one port type per session, each typed with its own. ridl-loopback makes the choice a type parameter: Loopback::new(catalog) carries FlatBuffers, and Loopback::<E>::with_encoding(catalog) carries E.

Signals. SignalReader::read copies a signal's current value into a buffer and returns its provenance, its freshness and its envelope. SignalWriter stages a change with set, invalidate or touch, and commit publishes every staged change with one timestamp per interface, so that several signals of one interface updated together appear as one publication. A read fails with ReadError, a staged change with WriteError; commit cannot fail.

Events. EventSource subscribes to and unsubscribes from the events of an interface, and next takes the next occurrence of anything subscribed, with its interface and its ordinal. EventSink::raise sends one occurrence; an occurrence is not staged and has no commit. A subscription fails with SubscribeError, next with ReadError, and raise with RaiseError.

Calls. Caller sends a command or a query and returns a Correlation, the identifier of that call to its caller. ack reads a command's acknowledgment and reply a query's reply, once each is known, and forget releases a correlation whose outcome the caller no longer needs. Handler::serve starts presenting the calls to the listed members, next_claim presents each delivered call once as a Claim, and settle gives the claim its outcome: the reply bytes, or the CallError the caller sees. A send fails with SendError, a serve with ServeError, next_claim and reply with ReadError, and a settlement with SettleError. The outcome of a call is a CallError from ridl_rt::error, not a port error.

Fixed. FixedReader::read_fixed copies a provisioned value into a buffer. It fails with ReadError. How a value is provisioned into the runtime is the runtime's own API, not a port.

Extensions. A runtime may omit ScannableSignals and CoherentSignals, because they describe mechanisms that some runtimes have. ScannableSignals reports a generation counter for each interface and writes the signals that changed since a Watermark; neither method returns an error. CoherentSignals::read_coherent answers several ordinals of one interface from one publication and fails with ReadError. A runtime whose transport delivers each field separately cannot present it. Wakeable::wake_on stores a waker for an Interest — a call's outcome, a free call slot, an event, or a claim — and wakes it when that interest may have changed. A runtime that serves a generated async client implements Wakeable, because every face future that waits is bounded on it.

The documentation of the event and call traits also states how a runtime delivers the trace context a sender passes. Every error enum of ridl_rt::port is #[non_exhaustive].

Testing a port

The crate ridl-rt-conformance holds the port contract tests as functions generic over a runtime. A runtime runs the whole suite from its own tests. Add it as a dev-dependency at the same version as ridl-rt, because its public surface follows the port contract of that version. A patch release can add tests to the suite, so a runtime that wants a fixed set of tests pins the crate with =. This Cargo.toml fragment is an illustration and is not compiled:

[dependencies]
ridl-rt = "0.14.0"

[dev-dependencies]
ridl-rt-conformance = "=0.14.0"

In the test crate, implement the Factory trait on a type of that crate — a unit struct is enough, and the orphan rule forbids implementing it on the runtime's own type from outside the runtime. Runtime is one value that implements Attached, Clock, SignalReader, SignalWriter, EventSource, EventSink, Caller and Handler: an aggregate handle. Source, Caller and Handler are a second event source, caller and handler on the same runtime. SLOTS is the number of calls the runtime holds at once, at least 1; the tests fill the call table, so a runtime with no bound cannot run them. runtime builds a runtime attached to a catalog, with a clock that moves only when advance moves it. fail_next_settle makes the next settlement fail once.

Then call suite!, which writes one #[test] per test. The flags after the semicolon add the tests of the extensions the runtime implements: scannable, coherent and wakeable, and trace for a runtime that carries the trace context. suite!(MyFactory) alone runs the tests of the ports every runtime presents. This skeleton is an illustration and is not compiled; MyRuntime and the handle types stand for the runtime's own types:

use ridl_rt::contract::CatalogRef;
use ridl_rt::sample::Duration;
use ridl_rt_conformance::Factory;

struct MyFactory;

impl Factory for MyFactory {
    type Runtime = MyRuntime;
    type Source = MySource;
    type Caller = MyCaller;
    type Handler = MyHandler;

    const SLOTS: usize = MyRuntime::SLOTS;

    fn runtime(catalog: CatalogRef) -> MyRuntime { /* ... */ }
    fn source(runtime: &MyRuntime) -> MySource { /* ... */ }
    fn caller(runtime: &MyRuntime) -> MyCaller { /* ... */ }
    fn handler(runtime: &MyRuntime) -> MyHandler { /* ... */ }
    fn advance(runtime: &mut MyRuntime, by: Duration) { /* ... */ }
    fn fail_next_settle(runtime: &mut MyRuntime) { /* ... */ }
}

ridl_rt_conformance::suite!(MyFactory; scannable, coherent, wakeable, trace);

The wakeable flag also requires that the three role handles implement Wakeable, and that the factory and the handles are 'static, because one test runs on a thread of its own. The working example is crates/ridl-loopback/tests/conformance.rs, which runs every test of the suite, with all four flags, over ridl-loopback.

The suite does not test every case. The one list of what it leaves out is the section What the suite leaves out of the crate documentation; a runtime that wants one of those cases tested keeps its own test of it.

What a binding decides

A runtime that carries frames to a second process does so through a binding: the frame specification carried over one transport. A binding is written from that specification, the ridl-rt design record for the exact shape of each name, and the projection record of the encoding its path carries. Its own document states the nine items of §10, each a choice the frame leaves to the transport:

1. How a consumer reaches a provider, what opens and ends the session, and what an ended session is on that transport, so that Detached and Transport::Down have a cause.
2. The byte layout, order and width of each header field, and how the frame's form is carried. An interface number or an ordinal keeps its 32-bit range, or the binding refuses it at attach time.
3. Which payload encoding the path carries, as an encoding tag.
4. Where one frame ends and the next starts on a stream, how a payload's length is carried, and what happens when that framing is lost.
5. What the provider derives a caller's identity from for duplicate suppression, and whether that identity survives a reconnect.
6. How long a settled response is kept for a call that has no response bound.
7. Whether the frames of one commit cross as one unit, and so whether a runtime over the binding presents CoherentSignals.
8. On a path that maps a buffer instead of sending a frame, which header fields are in the mapped region's own layout and which are in a frame beside it. The control plane is framed on every binding.
9. The answer to a call that arrives faster than its rate floor, when the binding enforces one.

A binding adds nothing to the frame. It does not change the field set, the meaning of a field, what a receiver does with a frame, the per-kind presence rules, the invalid payload rules, or the control-plane operations. §11 names the bindings, and §12 lists the sixteen statements a second implementation — a runtime, a binding, or both — shows with its own tests to conform.

One binding is built in this repository: the WebSocket binding of §11.1, whose Rust side is ridl-transport-ws, a server over a ridl-rt port set the embedding program chose. On Android a runtime binds the ports over its own binder contract, outside this repository. ridl-loopback runs in process and speaks no frame. The frame chapter is a specification, and its As-built note says which of its rules the transport applies; see the note at the top of frame.

Attaching to a catalog

A port attaches to one catalog. The rule for attaching is §6.1 of the frame specification.

Further reading

• ridl_rt::port — the exact shape of every port trait and error.
• ridl-rt-conformance — the Factory trait, the suite! macro, and what the suite leaves out.
• ridl-rt — the design record of the runtime library, including its ports.

The catalog descriptor

The catalog descriptor is a small binary file, one per unit, that lists what a runtime needs to route and check the traffic of that unit's interfaces: the interface numbers, the members and their ordinals, the maximum encoded size of each payload, the timing bounds, and the retired interfaces. A program reads it without the compiler and without decoding the IR. A unit is one ridl.toml with a [package] table and every source package in its directory tree; the unit's name is the manifest's name, which is also the name of its root source package (the design record).

What it is for

A process that carries interactions between other processes — a gateway, a broker, a bridge between two transports, or the engine of a runtime — does not link the generated crate of every unit it carries. It still has to answer questions such as:

• Which interface does the number in this frame name, and is that interface retired?
• Is this member a signal, an event, a command or a query, and which payload does it carry?
• What is the largest payload this member can send, so that a buffer can be sized in advance, and so that a larger payload can be refused? The size counts the payload alone, without the envelope and the framing a transport adds.
• What timing bound does this member declare?
• Do both peers speak the same version of the unit?

The catalog descriptor answers each of these from one file per unit, read at startup.

What is built. The compiler writes the descriptor, the ridl-descriptor crate reads and verifies it, and ridl describe prints it. No gateway, broker or engine that reads it exists in this repository yet; those are the consumers it is designed for. The generated Rust face does not read the file either: it carries the catalog name and hash it needs as constants (see The catalog and the face). Codegen plugins do not read it; the codegen model carries the same facts (see Writing a codegen plugin).

Producing it

--emit catalog writes one <unit>.catalog.binfb file per unit that declares at least one interface, or a service with an inline body, in any of its source packages:

ridl build examples/cabin --emit catalog --out-dir out
# writes out/veh.cabin.catalog.binfb

A unit with no interface gets no file. The flag combines with the others, so one build can write the Rust crate and the descriptor together. The other emit targets stay one file per source package; only the catalog is per unit.

Reading it

ridl describe verifies a descriptor and prints it as JSON:

ridl describe out/veh.cabin.catalog.binfb

The top of the output for examples/cabin, with the 32 bytes of the hash left out. toolchain is the version of ridl that wrote the file, so it changes with each release; the excerpt shows it as <version>:

{
  "compatible": [],
  "hash": [ ... ],
  "interfaces": [
    {
      "members": [ ... ],
      "name": "Cabin",
      "number": 1,
      "provisional": true,
      "reserved_ordinals": []
    },
    ...
  ],
  "name": "veh.cabin",
  "retired": [],
  "toolchain": "<version>",
  "version": 1
}

The member average, a query, as it appears in members:

{
  "kind": "Query",
  "limit": null,
  "name": "average",
  "ordinal": 4,
  "payloads": [
    {
      "max_sizes": [
        { "bytes": 46, "cause": "Unspecified", "encoding": "FlatBuffers", "state": "Bounded" }
      ],
      "role": "request",
      "type_name": "Window"
    },
    {
      "max_sizes": [
        { "bytes": 44, "cause": "Unspecified", "encoding": "FlatBuffers", "state": "Bounded" }
      ],
      "role": "response",
      "type_name": "Average"
    }
  ],
  "timing": { "max_us": "200000", "min_us": null, "mode": "Range" }
}

The keys are in alphabetical order, and an absent timing bound or limit is null. A file that is not a valid descriptor, or that has a schema version this toolchain does not read, makes ridl describe exit with code 2. The CLI reference has the details.

What it contains

• The catalog: the unit name; the hash, which identifies this version of the unit (see below); toolchain, the version of ridl that wrote the file; the schema version; the interfaces; the retired interfaces, each with its name and number, so a reader can refuse a peer that still uses one; and compatible, the hashes of earlier catalogs of the unit that the toolchain judged compatible or carried over unchanged with this one (see The compatible catalogs).
• Each interface: its name, qualified relative to the unit (Cabin for an interface of the root source package, cluster.Speed for one of the source package cluster below it); its number, which is one space per unit; and provisional, which is true while the number is not yet recorded in the unit's interfaces.lock, the one lock file beside the unit's ridl.toml. Cabin above is provisional because examples/cabin has no lock file; a number becomes permanent when ridl lock records it. reserved_ordinals lists the ordinals that reserved tombstones hold. The ridl reference, section 11, is the rule for the names and the numbers.
• Each member: its name, its ordinal (its position in the interface body), its kind, its payloads, its timing when the member declares one, and its limit, the payload limit in bytes that a [limits] entry of the unit's ridl.toml gives it, absent when no entry applies.
• Each payload: its role (value for a signal or a fixed, occurrence for an event, request for a command or a query, response for a query's reply), its type_name, and one max_sizes row per encoding. A row is Bounded, with bytes the maximum encoded size of the payload, envelope and framing excluded; or Unbounded, with bytes 0 and a cause that says why the compiler cannot bound it in that encoding. For example, a FlatBuffers row is Unbounded when the payload's largest encoding would exceed 4 GiB, the most that FlatBuffers' 32-bit offsets can address. An encoding with no row has no size computed by this toolchain. A stream payload, a request of zero or of several parameters, and an inline T | E reply have no row in any encoding. A podbuf row is present for a payload with a podbuf root, sized by ridl_ir::projection::podbuf::max_size, and a proto3 row is present only for a payload that is a struct, a union, a named scalar, an enum or an enum set, the kinds the proto3 schema gives a message of their own. A named scalar, an enum and an enum set are sized as their root message <Name>Box.

The descriptor does not contain type layouts, field lists, constraints other than the ones that bound a payload's size, contract clauses, or initial values. A reader that needs a payload's shape reads the schema that the wire backend emits.

The compatible catalogs

The hash identifies one version of the unit exactly. compatible lists, as 32-byte hashes, the earlier versions of the unit that ridl diff's classifier, scoped to the unit, judged compatible with this one, newest first. When the current hash is the newest published one, the catalog did not change, and the published list is carried whatever the classifier's verdict. The current hash is never in it. A reader built for one of those versions can be accepted by a provider that serves this one, which is the use the frame specification makes of the list (section 6.1). No runtime in this repository accepts an attach on the strength of the list.

The list comes from the published baseline. ridl baseline records, for each unit with an interface, a <unit>.catalogs file beside the snapshots, and ridl build reads it. The list is empty when there is no baseline, when the unit has no file, and after a breaking change that changes the catalog, which restarts the chain. A file is used only when its newest hash is the hash recomputed from the snapshots published beside it; a file that does not describe those snapshots, such as one left behind by a hand-edited baseline, restarts the chain instead. A breaking change that leaves the catalog hash as it was, such as the removal of a declaration no interface reaches, keeps the chain. A change in another unit counts for this unit only when an interface of this unit reaches the changed declaration. ridlc build reads no baseline and writes an empty list. The CLI reference states the file format and the rules.

The catalog and the face

The catalog hash is a SHA-256 hash over the unit's interfaces, from every source package of the unit, their numbers, and every declaration they reach, in the unit or in another one. Doc comments, labels and deprecated do not change it; any other change to an interface or to a type it uses does, so a change in any source package of the unit that an interface reaches changes the one hash. A [limits] entry in the unit's ridl.toml that gives an interaction its payload limit changes the hash too, so adding, removing or editing such an entry changes the hash of the interaction's unit. The design record's hash section has the exact input.

The generated Rust face carries the same unit name and hash as its CATALOG. When a face binds to a port, it compares its CATALOG with the catalog of that port, and panics when they differ. So a face generated from a different version of the unit than the one its runtime serves fails at bind time, instead of misreading payloads. The face compares itself with its own port only; it does not compare catalogs with the party at the other end. The failures section of "Using the generated Rust code" shows what that check does.

Stability

The file is a FlatBuffers buffer with the file identifier RDLC. Its schema evolves by appending only: a field is added at the end of its table, and no field is removed, reordered or retyped. A reader built against an older schema ignores the fields it does not know. The version field is the schema version, now 1; a reader refuses a version other than the one it was built for.

A Rust program reads the file with the ridl-descriptor crate, published on crates.io. Its verify function checks the whole buffer before it returns a view, so a later read cannot fail on a malformed offset. With its default features off the crate is no_std with alloc and keeps verify, the accessors and finish; the parts that build a descriptor from the IR need the standard library and come with the std feature. The default dedup feature makes finish write each repeated vtable, string and byte vector once. With it off as well, a reader links no hashing crate, and finish writes a larger but valid file.

Not built yet

The design also defines a system descriptor, one per deployment. It is not built; the design record lists it with the other parts that are not built.

Further reading

• The catalog descriptor — the design record: the schema, the hash input, the size states, and the verifier.

Evolving an interface

An interface changes after it ships: a signal gains a sibling, a bound is tightened, a payload type is replaced. This chapter shows how to change one so that the toolchain can tell a consumer built against the old version from one built against the new version, and what it records about each change. It covers the three commands that carry the workflow — ridl lock, ridl baseline and ridl diff — a table of the verdicts, and the list of compatible catalogs that the toolchain writes into the catalog descriptor.

What identifies a version

Two identities are involved, and they answer different questions.

• The interface number says which interface. It is allocated once, by ridl lock, and recorded in the unit's interfaces.lock. A rename keeps it and a retirement keeps it forever, so a number is never given to a different interface. The ridl reference, section 11, is the rule.
• The catalog hash says which version of the unit. It is a SHA-256 hash over the unit's interfaces, their numbers, and every declaration they reach. The catalog descriptor describes it.

A unit is the package or workspace member that owns one ridl.toml, and it has one interfaces.lock. The workflow below keeps the numbers stable and records each published version's hash.

The workflow

The workflow has four steps. Steps 1 and 2 run once for a new unit; steps 3 and 4 repeat for every release.

1. Record the numbers. ridl lock gives every interface that has no entry the next free number and writes interfaces.lock. Until it runs, an interface has a provisional number, which is no identity: ridl baseline refuses to publish a provisional number (RIDL-411).
2. Publish a baseline. ridl baseline writes one <package>.ir.json snapshot per source package, and one <unit>.catalogs file per unit that has an interface, under .ridl/baseline/ at the workspace root. Commit the directory: it is the record of what was released.
3. Change the source, then compare. ridl diff compares the published baseline with the working tree and prints a verdict. ridl check also reads .ridl/baseline/ when it exists, and warns (RIDL-407) on a change that moves an interaction's position.
4. Publish again when the release is ready. ridl baseline replaces the snapshots and extends the <unit>.catalogs file.

For a unit with one package, the first publication is:

ridl lock . && ridl baseline && find .ridl/baseline -type f | sort

allocated Cabin 1
.ridl/baseline/demo.cabin.catalogs
.ridl/baseline/demo.cabin.ir.json

Comparing with ridl diff

ridl diff takes the old and the new side as snapshots, a directory of snapshots, or source. To compare the published baseline with the working tree, pass the baseline directory and the tree:

ridl diff .ridl/baseline .

The report lists each change with its category and its verdict, then prints the overall verdict as its first line. The exit code is 0 for identical and compatible, 1 for breaking, and 2 when a side does not compile or an input is missing. A pipeline that must not ship a breaking change can run the command and stop on exit 1. Appending an event to the interface:

compatible
  [compatible] interaction_appended demo.cabin/Cabin/doorLocked: (absent) -> event doorLocked

ridl diff --explain <category> prints the rule for one category, and the CLI reference lists every category.

Renaming and retiring

A rename and a removal are not edits of the source alone, because the number records the identity.

• To rename an interface, change its name in the source and run ridl lock . --rename Old=New. The number is kept, and ridl diff reports interface_renamed, which is compatible on the wire.
• To remove an interface, delete it from the source and run ridl lock . --retire Name. The entry keeps its number with the word retired, and ridl diff reports interface_retired. Without the retirement, the build fails with RIDL-409 and ridl baseline publishes nothing.
• To remove an interaction, replace it with a reserved line that holds its position. A bare deletion is breaking, and ridl baseline refuses it (RIDL-408).

The verdicts

ridl diff gives each change one of two verdicts, compatible or breaking, and the report's verdict is the worst of them. identical means there is no change at all. A verdict says whether a consumer built against the old version still works with the new one. It does not say whether the catalog hash changed, and the two are separate questions: the hash identifies an exact version. A compatible change that reaches the hash makes a new version, and a change that leaves the hash unchanged makes none.

The one transport in this workspace is the WebSocket binding. The Rust crate ridl-transport-ws serves it, and the TypeScript package @driftsys/ridl-transport-ws (packages/ridl-transport-ws/) is its consuming side, for Deno and the browser. The crate opens no descriptor file itself. Its embedder may supply a member table that lists the compatible hashes, built by hand or, with the crate's descriptor feature, from the bytes of the catalog descriptor: with one, the crate accepts an attach naming a listed earlier hash, as the last column shows; without one, it accepts an exact match of the hash only. The last column states what the frame specification (section 6.1) specifies for an older consumer, built against the version before the change.

The "compatible" and "breaking" rows cover the categories that ridl diff prints. The rules are in the CLI reference, and ridl diff --explain <category> prints the rule for one. These are the common cases:

• Compatible: an interaction appended after every slot that was used before (interaction_appended); an interaction retired to a reserved line in its own slot (interaction_retired); an interface added, renamed with its number kept, or retired (decl_added, interface_renamed, interface_retired); a scalar constraint widened (constraint_changed); a signal or event bound tightened (timing_changed); an interface joining or leaving a service's list (service_interface_added, service_interface_removed).
• Compatible, and the hash may change: an enum body reordered with no number changed (enum_reordered), which changes the hash when an interface reaches the enum, and a provisional interface number frozen by ridl lock (interface_frozen), which always changes it.
• Breaking: an interaction inserted, removed without a tombstone or reordered (interaction_inserted, interaction_removed, interaction_reordered); a payload, a parameter list or a return shape changed (payload_changed, params_changed, return_changed); a scalar constraint narrowed or a width changed (constraint_changed, width_changed); a declared payload limit raised, lowered, added or removed (limit_changed); a signal bound loosened or removed; a struct field, a union arm or an enum value removed, an enum value renumbered, or an interface number changed (decl_removed, member_reordered, interface_number_changed).
• Breaking under podbuf: a struct field appended to a struct that another struct, a tuple or an exact-length array holds inline anywhere in the new side, in a struct, in the argument struct a call with several parameters induces, or in a tuple reply (podbuf_inline_append). A podbuf head holds such a struct at a fixed offset, so the inline copy cannot grow without moving the fields after it; the other encodings hold no struct inline. The line names each inline use. A snapshot does not record the encodings a workspace builds, so the verdict follows ridl diff --encoding podbuf: breaking with it, compatible without it, under the heading breaking under podbuf either way. The search mirrors the heads the encoder lays out, a declaration and a named induced tuple: a struct that is a root of its own (a single named parameter, a named reply, a signal, event or fixed payload), that is used only as the element of a bounded array, the key or value of a map entry, or a union arm, or only inside an exact-length array that is itself a root (a fixed payload [S; 2..2], which has no head) can grow under podbuf, and such an append is compatible. A tuple inside such a root is a head, and a struct inside that tuple is a use. Also breaking under podbuf: an enum value, an enum-set flag or a union arm appended after which the podbuf integer of the enum or the enum set or the tag of the union is a different integer, by width or by signedness: a value above 255, a flag at bit 8 or an arm past ordinal 255 (u8 to u16), a value above 65535 or a flag at bit 16 (u16 to u32), or a value above 4294967295 or a flag at bit 32 (u32 to u64). An enum's integer is the narrowest that holds every value, signed when a value is negative. A negative value appended to an enum that has values is an insert below its highest value, which is a breaking decl_added and draws no width line, so the integer turns signed only when an enum with no value gains values (-1 gives u8 to i8). The width change is reported once per declaration as podbuf_width_change with the old and the new integer, under the same heading and with the same verdict rule; every head that holds the enum, the enum set or the union lays out a different integer, and an append that keeps the integer draws no such line. Without --encoding podbuf the line is reported compatible, which holds under proto3; an enum-set flag that widens the integer also widens the enum set's FlatBuffers scalar, which ridl diff --encoding flatbuffers does not report yet (driftsys/ridl#1120). Also breaking under podbuf: an enum value or an enum-set flag appended. Every enum and enum set is strict, and the verify of an older reader refuses a value or a bit its declaration does not name. It is reported once per declaration as podbuf_strict_enum_append, under the same heading and with the same verdict rule, except that an enum or an enum set whose append changes the integer draws only the podbuf_width_change line. A field removed from a struct, its slot held by a tombstone, is decl_removed, breaking under every encoding: the type is gone from the source, so its bytes cannot be kept.

An interface that joins the list of a service with a named interface list, or leaves it, is not part of the hash input, because the list is not hashed. Such a change is compatible, and it leaves the hash as it was.

The verdict that decides the chain is the verdict of one unit, not the report's overall verdict. It is the worst verdict among the changes that concern the unit: a change in one of its source packages, or in a declaration that an interface of the unit reaches, in the unit or in another one. A breaking change in a declaration of another unit that the unit does not reach leaves the unit's chain as it was, although ridl diff still exits 1 for the report as a whole. A breaking change in a declaration of the unit's own packages that no interface reaches is breaking for the unit, although the hash stays as it was. The chain is then carried, because the catalog did not change and every listed hash stays compatible.

The compatible catalogs

The catalog descriptor of a unit carries, beside the unit's own hash, a compatible list: the hashes of earlier versions of the unit that the toolchain judged compatible with this one, newest first. The current hash is never in it. The frame specification uses the list at attach: a provider may accept an attach that names one of those hashes (section 6.1 states the rule). No runtime in this repository accepts an attach on the strength of the list. The toolchain writes it, and a runtime that reads it is outside this repository. The generated Rust face compares its own CATALOG with its own port only, and does not read the list. This section describes what the toolchain writes.

The chain file

ridl baseline keeps the history in .ridl/baseline/<unit>.catalogs, one file per unit that has an interface, or a service with an inline body. The file is text: a first line that starts with #, then one catalog hash per line as 64 lowercase hexadecimal characters, newest first.

# catalogs of this unit's published baselines, newest first, back to the last breaking change
a5973898ecf39cce4b375906dfdbcafc795108832593b70dd49f3e75a90ca841
5ca96801a44963f58aca2dd05a73736c51fa199a2070cdf0a773360294a071db

The first hash is the catalog hash of the baseline being published, the same hash that ridl build --emit catalog computes. The hashes after it are copied from the replaced file when the change is compatible or the hash is unchanged, and a breaking change that changes the hash restarts the file with the new hash alone; the rules are in the ridl baseline reference.

For a unit with a published snapshot, a file that cannot be read, or that has a line that is neither a comment nor a hash, or that lists a hash twice, stops ridl baseline with exit 2. ridl build also exits 2 when it writes a catalog descriptor or generates code and the workspace compiles without an error diagnostic. The message names the file and the line, and says to repair the file or remove it to start the unit's chain again.

The build writes the list

ridl build reads the baseline when it writes a catalog descriptor or generates code. For each unit that has an interface and a package in the baseline, it lists the hashes of the unit's <unit>.catalogs file, less the current catalog hash, when the unit's verdict from the baseline to the working tree is compatible or identical, or when the current hash equals the first hash of the file. It writes the list into the descriptor, which ridl describe prints as compatible, and into the catalog.compatible field of the codegen model that a plugin receives. The recorded file is not changed by a build; only ridl baseline changes it.

The list is empty in these cases:

• the workspace has no .ridl/baseline/ directory, or the directory holds no .ir.json snapshot;
• the baseline holds no package of the unit;
• the unit has no <unit>.catalogs file;
• the unit's verdict from the baseline to the working tree is breaking and the current hash differs from the first hash of the file.

A build with an error diagnostic writes no list. A build whose only errors are RSDL-7xx still writes its artifacts, with an empty list.

ridlc build reads no baseline, so the descriptors and the codegen requests it writes carry an empty list. ridl build is the command that fills it.

So a working tree that adds a signal to a published interface is built with a list that holds the published hash. After the next ridl baseline, the file holds the new hash first and the published hash after it, and a later build of the same tree lists the published hash and no other.

An example

The unit demo.cabin declares an interface Cabin with a signal currentSpeed and an event doorChanged. After ridl lock and the first ridl baseline, the file holds the one hash of that baseline:

# catalogs of this unit's published baselines, newest first, back to the last breaking change
5ca96801a44963f58aca2dd05a73736c51fa199a2070cdf0a773360294a071db

An event doorLocked, with a doc comment, is appended to Cabin. The change is compatible, and a build of the tree writes a descriptor whose compatible list holds one hash, the published 5ca96801.... Publishing again puts the new hash first:

ridl diff .ridl/baseline . ; echo "exit: $?"
ridl baseline && cat .ridl/baseline/demo.cabin.catalogs

compatible
  [compatible] interaction_appended demo.cabin/Cabin/doorLocked: (absent) -> event doorLocked
exit: 0
# catalogs of this unit's published baselines, newest first, back to the last breaking change
a5973898ecf39cce4b375906dfdbcafc795108832593b70dd49f3e75a90ca841
5ca96801a44963f58aca2dd05a73736c51fa199a2070cdf0a773360294a071db

Next, currentSpeed changes its payload type from Speed to DoorState. The change is breaking, so a build of the tree writes an empty compatible list. ridl baseline does not refuse the publication, because it enforces the numbers and the tombstones, not the verdict. It restarts the chain:

ridl diff .ridl/baseline . ; echo "exit: $?"
ridl baseline && cat .ridl/baseline/demo.cabin.catalogs

breaking
  [breaking] payload_changed demo.cabin/Cabin/currentSpeed: Speed -> DoorState
exit: 1
# catalogs of this unit's published baselines, newest first, back to the last breaking change
4a83686ad26f656d469694a346b1eebb0f851becf05c95e173a4a29bc1496269

A consumer built against either of the two earlier versions is not on the new list, so the rule of section 6.1 would not accept it.

Further reading

• ridl lock, ridl baseline and ridl diff in the CLI reference, with the exit codes and the publication gate.
• The catalog descriptor — the file that carries the hash and the compatible list.
• The ridl reference, section 11 — the rule for numbers, retirement and tombstones.
• The catalog descriptor design record — how the hash and the chain are computed.

Documenting your API

A contract is read by more people than the ones who write it: the authors of each component that offers or requires it, the reviewers of a change, and the assistant that completes a line in an editor. A doc comment is where the contract says what a type, a field or an interaction means. This chapter covers where a doc comment goes, what it can hold, and the lints that check it. The rules are in the typl reference §14, and the decisions behind them in ADR-0026.

What is built. The checker reads the doc comment of every declaration and every member, resolves the links in it, and stores the doc, the resolved links and the tags in the IR. The language server shows them on hover and in completion. The doc lints of this chapter are reported by ridl check, ridl build, the language server and the MCP tool ridl_check, with the levels of the project's [lints] table.

The Rust and TypeScript backends write the docs, their links, the @see, @since and @deprecated tags and the item's rules into the generated code, as Using the generated Rust code describes.

What is not built. There is no ridl doc command that writes a documentation site.

A documented package

A doc comment is written on the lines directly above the item it documents. Here is a small package with every item documented:

package docs.cruise

/// A vehicle speed over ground, as the brake controller computes it from the
/// four wheel speed sensors.
/// @since 1.0
type Speed: km/h [0.0..250.0 step 0.5]

/// The position the driver moved the cruise control lever to.
enum LeverCmd {
  /// The lever is at rest.
  NONE = 0
  /// Raise the set speed by one step. The step is the `step` of [Speed].
  UP = 1
  /// Lower the set speed by one step.
  DOWN = 2
  /// Switch cruise control off. The set speed is kept for a later resume.
  CANCEL = 3
}

/// The state that [CruiseControl] publishes after each lever command.
struct CruiseState {
  /// Whether cruise control holds the vehicle at [CruiseState.setSpeed].
  engaged: Engaged
  /// The speed cruise control holds while it is engaged.
  setSpeed: Speed
}

/// Whether cruise control is engaged.
type Engaged: boolean

/// The cruise control function of one vehicle.
///
/// The interface accepts lever commands from the steering column switch and
/// publishes the resulting state.
/// @see docs.cruise.LeverCmd
interface CruiseControl {
  /// The current cruise control state. A consumer that subscribes late reads
  /// the last published value.
  signal status: CruiseState @[50ms..500ms]

  /// Applies one lever command. The outcome is published on
  /// [CruiseControl.status]; the command does not return it.
  command setLever(
    /// The lever position read from the switch.
    cmd: LeverCmd
  ) @[..100ms]
}

The rest of this chapter takes the parts of this example one at a time.

House style

• Write doc comments as /// lines. The compiler also accepts the block form /** ... */ with the same meaning, and ridl fmt does not rewrite one form into the other. A project that wants only /// turns on the doc-comment-style lint (see The doc lints).
• Start with one sentence that says what the item is. Add a blank /// line and more paragraphs when the reader needs them.
• Say what the declaration itself cannot say: what a value means, where it comes from, and what happens when it changes. Do not repeat the range, the unit or the timing. The editor shows those from the declaration itself, in the Contract part of the hover (see In the editor).
• Document an interface by its responsibility, and document each interaction on its own line. The interface doc does not list its members.

Where a doc comment goes

A doc comment documents the next named declaration or member. These are the positions that take a doc comment, called carriers:

"Must have a doc" is what the missing-docs lint checks. A package needs no doc.

A doc comment in any other position draws misplaced-doc-comment: before package, before an import, before a return type or an attribute block, and at the end of a file or of a body. Each of these positions either has no name to document or belongs to the item around it.

No blank line may separate a doc comment from its carrier. A blank line draws detached-doc-comment.

Parameters

A parameter takes a doc comment, as cmd does in setLever above, but never needs one. Every parameter type is a named type, and the named type carries its own doc and its own rules. When a parameter has no doc of its own, the editor shows the doc of its type instead, under the line "From TypeName:".

rsdl

The five rsdl declarations are carriers, and so is each line of their bodies:

/// The cruise control computer in the front zone.
component CruiseEcu {
  /// The function the driver controls with the steering column lever.
  offers docs.cruise.control
}

The docs of the declarations, of the system and distribution member lines, and of the offers and requires lines are stored in the system IR. A placement line in a machine takes a doc too, and the editor shows it on hover, but the system IR has no field for it.

What a doc comment holds

A doc is CommonMark: paragraphs, lists, emphasis, code spans and fenced code blocks.

Links

A name in square brackets is a link to a declaration or a member. Three forms are links:

The bracket content is a link only when it is a name: one or more dotted segments. [0..250] and [see below] are prose. A name inside a code span or a fenced code block is not a link. A [Name] that has a CommonMark link reference definition ([Name]: https://...) in the same doc is an ordinary Markdown link.

A link resolves in the scope of the file that holds it, by the rules of a type reference:

• A bare Name is looked up as a type name is: a declaration of the package, then an imported name (an import alias leads to the declaration it names), then ridl.std.
• A qualified pkg.Name reaches any package that the current package can depend on — another member of the workspace, or a package of [imports] — whether or not the file imports it. A doc link never makes you add an import that the code does not use. A remote package of [imports] is reachable where an import of it would resolve: the package's own [imports], or the workspace [imports] for a member, must pin its unit. A link into a remote package no such pin reaches draws broken-doc-link.
• One more segment names a member of the declaration: a field ([CruiseState.setSpeed]), an enum value ([LeverCmd.UP]), an enumset bit, a union arm, or an interaction ([CruiseControl.status]).
• A declaration that is internal in another package cannot be linked to, because documentation of the other package could not show it. A link to an internal declaration of the same package resolves.

A link that does not resolve draws broken-doc-link, and the IR does not store it.

Tags

A tag is a word that starts with @, at the start of a line of the doc. Four tags exist:

A tag may appear more than once; every value is kept. An @ that is not at the start of a line is prose. A tag line is not part of the doc text: a doc made only of tags has no text, and missing-docs treats it as missing.

@see and @since change only documentation. @deprecated and @labels are stored in the IR beside the doc on a declaration, a struct field, an interface, an interaction and a service, and a backend that emits deprecation or label metadata reads them there. On an enum value, an enumset bit, a union arm, a parameter and an rsdl declaration or body line the two tags are accepted and dropped, with no diagnostic (ADR-0026 decision 4).

package docs.history

/// A request to change the gear.
/// @since 1.2
/// @see docs.history.GearBox.setGear
/// @labels SIL_2
struct GearRequest {
  /// The gear to change to, from 1 to 6.
  gear: Gear
}

/// A gear of the six-speed gearbox.
type Gear: integer [1..6]

/// The gearbox controller.
interface GearBox {
  /// Requests a gear change.
  command setGear(request: GearRequest) @[..20ms]

  /// The previous gear request, kept for clients built against version 1.0.
  /// @deprecated "use setGear"
  command requestGear(request: GearRequest) @[..20ms]
}

Examples

Write a usage example under a # Examples heading, with a fenced code block. This is a convention, not a tag: the compiler does not read it, and a name inside the code block is not a link.

package docs.examples

/// A distance to the vehicle ahead.
///
/// # Examples
///
/// ```ridl,ignore
/// signal gap: Gap @[50ms..200ms]
/// ```
type Gap: m [0.0..250.0 step 0.1]

The doc lints

Each doc lint is a TYPL- code, because doc comments are part of typl and every language of the family shares them. All of them are warnings; doc-comment-style is allow by default, so it is reported only when a project sets its level. The lints page explains levels and the [lints] table.

The examples below each draw one documentation lint on purpose. Some also draw the design lints explained beside their source blocks.

missing-docs

missing-docs is reported once per item, at the item's name. Its quick fix in the editor inserts an empty /// line above the item. Here Odometer has no doc, and internal exempts Raw and its field:

package docs.missing

type Odometer: km [0.0..1000000.0 step 0.1]

/// A raw sensor sample, for the use of this package only.
internal struct Raw {
  value: Odometer
}

The inconsistent-unit lint also reports value here. It uses km, while fields named value in other book examples use km/h. The book checks its whole-file examples as one workspace.

When you check from inside a workspace member, ridl check, ridl build, ridl lock and the MCP tool ridl_check report only the diagnostics of files under that member, so an undocumented item in a sibling member does not appear in that report. The language server reports every consumer file it loaded, and publishes no diagnostics for a file of a remote unit. A remote package of [imports] is checked: its errors fail the run, and the language server shows them in one window message per load; its warnings and infos, missing-docs included, are dropped before any [lints] level is applied.

A project that does not want to document every item yet sets the level in its ridl.toml:

[lints]
missing-docs = "allow"

broken-doc-link

package docs.broken

/// The heading in whole degrees, converted from a [Compass] reading.
type Heading: integer [0..359]

Compass is declared nowhere, so the link does not resolve.

detached-doc-comment

package docs.detached

/// The cabin air temperature.

type CabinTemperature: Cel [-40.0..85.0 step 0.5]

deprecated-without-reason

package docs.reason

/// The fan level of the first climate control version.
/// @deprecated
type FanStep: integer [0..7]

misplaced-doc-comment

A doc comment at the end of a body has no item after it:

package docs.misplaced

/// The wiper speed.
enum WiperSpeed {
  /// The wipers are off.
  OFF = 0
  /// The wipers run once every few seconds.
  SLOW = 1
  /// The wipers run continuously.
  FAST = 2
  /// A fourth speed is planned.
}

unknown-doc-tag and malformed-doc-tag

package docs.tags

/// The tyre pressure of one wheel.
/// @author the chassis team
/// @since next
type TyrePressure: kPa [0.0..500.0 step 1.0]

@author is not one of the four tags, and next is not a version.

doc-comment-style

doc-comment-style reports every /** */ doc comment, so a project that sets it to warn or deny requires ///:

[lints]
doc-comment-style = "deny"

Its quick fix in the editor rewrites the comment as /// lines. The lint checks in one direction only: no setting requires /** */.

In the editor

The language server reads the docs from the same compile as the diagnostics, so it shows what ridl check reads:

• Hover on a declaration, a member, a parameter, an rsdl declaration or body line, or a use of any of them shows the signature, the doc, a Contract list, and the @since versions, the labels and the deprecation reason. The Contract list is read from the IR: the range, step, unit, length, pattern and collection bound of the type, the timing of a signal or event, the response bound of a command or query, the error type of a fallible query, and each require and ensure clause. A link in the doc is shown as a link to the target's file and line. Hover on a member used in a contract clause shows that member.
• Completion items carry the doc of the item they insert, except the member items offered after . in a doc link. Inside a doc comment, [ and . complete link targets, and @ at the start of a line completes the four tags.
• Go to definition, find references and rename work on doc links and @see targets in .typl, .ridl and .rsdl files. Renaming a type updates every link and @see that names it, in every member of the workspace.
• Quick fixes: missing-docs inserts a /// line, and doc-comment-style rewrites a /** */ comment as /// lines.

There is no signature help: the language has no call expression for it to serve.

Writing a codegen plugin

A codegen plugin is a backend that is an executable rather than a part of ridl. ridl build runs it once per package, writes one request to its standard input, reads one response from its standard output, and writes the files the response carries. A plugin can be written in any language that reads and writes JSON.

This chapter is a guide. Each fact it summarizes is owned by another record, and the chapter links to that record:

• docs/design/codegen-plugins.md — the plugin system as built: the contract, the process host, the reference plugins and the deployment section.
• IR — encodings and stability — the IR specification: the canonical encoding, the nesting bound, the compatibility rule and versioning.
• ADR-0020 decisions 8 to 12 — the binding choices behind the plugin system.
• CLI reference — every flag of ridl build.

Reading order

Read these in order before you write a plugin:

1. The IR specification §7 and §8: read schema first, parse leniently, and use a file ridlc wrote as a fixture.
2. plugin.proto: the request and the response.
3. model.proto: what the model carries, message by message.
4. deployment.proto: the deployment section, if your plugin lays out memory for a deployment.
5. crates/ridlc-gen-model/src/main.rs: a complete plugin.
6. The ridl build section of the CLI reference: how the plugin is found and what ridl does with the response.

Running a plugin

A plugin for the language kotlin is an executable named ridlc-gen-kotlin. ridl build runs it when you pass --plugin:

• --plugin kotlin looks for ridlc-gen-kotlin on PATH, in PATH order. On Windows, ridlc-gen-kotlin.exe is also tried.
• --plugin kotlin=/opt/gen/bin/kt-gen runs the executable at that path and skips the lookup. Messages still name the plugin ridlc-gen-kotlin.

The flag repeats, once per plugin, and is the same on ridlc build. A plugin runs beside the --emit targets, and --emit defaults to rust, so a build with --plugin and no --emit also writes the Rust files. The plugin runs once per package that the code emits are written for, ridl.std included when a package uses it. --plugin-timeout <SECONDS> sets how long one run may take before ridl kills it; the default is 60 seconds.

The plugin's standard error is passed through to the terminal. The error cases and their exit codes:

A plugin's failure exits 1, not 2, because the build completed and the failure is one of its findings (ADR-0010 decision 1). The messages of each case are listed in the design record, §4.

The protocol

There is no framing and no binary form. The request is one JSON document on the plugin's standard input; the plugin reads until the end of input. The response is one JSON document on its standard output. Both are canonical protobuf JSON, pretty-printed: keys are the proto3 JSON names, so the field artifact_base is the key artifactBase; enum values are written by name; 64-bit integers are decimal strings; and bytes fields are base64.

A plugin never writes files. It returns each file in the response as a path, relative to --out-dir, and a text or binary content, and ridl writes it. So --out-dir means the same for a plugin as for the rust emit.

The nesting depth. A request can nest deeply, because a type can nest. The IR specification §4 and §8 state how many JSON levels a reader must accept: at least 516, and 1,000 is recommended. Some JSON libraries stop below that by default, serde_json at 128 for example, and need one configuration step.

The response is read strictly. This toolchain's reader rejects a key the schema does not have, so a plugin must not add fields of its own to the response. A diagnostic is a severity and a message; there is no source span. An unset severity counts as an error.

The schemas

The schema of the request and the response is the protobuf package ridl.codegen.v1, in three files in crates/ridl-ir/proto/ridl/codegen/v1/:

• plugin.proto — CodegenRequest, CodegenResponse, GeneratedFile, Diagnostic, BackendOption;
• model.proto — the lowered model;
• deployment.proto — the deployment section.

plugin.proto imports the other two. The repository publishes no schema package of its own. Today an author copies the files from the release tag the plugin is tested against, as driftsys/ridlc-gen-kotlin does: it keeps the files unchanged and runs a check that fails when they differ from the pinned tag. Copy every file that the tag's plugin.proto imports: where the tag holds deployment.proto, that is all three files, and a plugin.proto that imports deployment.proto does not compile without it. An older tag holds only plugin.proto and model.proto.

Compatibility

The rules are the IR specification's §6 to §8. In short:

• Additive changes are made in place. A new field, a new enum value or a new oneof member can appear in ridl.codegen.v1 at any release. A plugin whose request reader is built on an older ridl-ir still rejects a request that carries a new enum value, so that plugin must be rebuilt against the ridl-ir that adds the value. Any other change — a removal, a rename, a renumbering, a change of type or of meaning — is a new package, ridl.codegen.v2, compiled beside the old one.
• A plugin reads the request leniently. It ignores keys it does not know, so a request from a newer ridl still reads. ridl_ir::codegen::request_from_json does this at every nesting level of the request, from ridl-ir 0.6.0 on. It still rejects an unknown enum name, because that changes the meaning of a known field, so a new enum value is a change an older plugin reports as an error. A Rust plugin built against an earlier ridl-ir rejects a request that carries a key that release does not know, and must be rebuilt once.
• A plugin refuses an unknown schema. schema is the first field of the request. A plugin that does not know its value answers with an error diagnostic naming both values. A plugin never refuses on toolchain, which only says which version of ridl wrote the request.
• The toolchain reads the response strictly, as the protocol section says.

What the request carries

ridl build --emit codegen-request writes the whole request for each package to <base>.codegen-request.json, so a plugin author can read what their plugin would receive without running it. The emit takes its options from a [backend.codegen-request] table, which is how a request carrying an option is written. Every excerpt in this chapter was read from that artifact, built from examples/cabin and called request.json below.

These values are the top-level fields of the request ridl build sends for examples/cabin, with model and deployment left out of the excerpt. toolchain is the version of ridl that wrote the request, so it changes with each release; the excerpt shows it as <version>:

jq '{schema, toolchain, options, artifactBase, generatedMarker, header}' request.json

{
  "schema": "ridl.codegen.v1",
  "toolchain": "<version>",
  "options": [],
  "artifactBase": "veh.cabin",
  "generatedMarker": "@generated by ridl from package veh.cabin. Do not edit.",
  "header": ""
}

• model is the lowered model of one package: its declarations, with type references resolved and names in every case the name transform defines (ADR-0016), its interfaces and their members, its services, and its catalog. It is the same JSON value that ridl build --emit codegen-model writes to <base>.codegen.json, one indentation level deeper, so that file is a fixture for a plugin's tests.
• options is a list of {key, value} pairs sorted by key. It holds one encodings option, the names joined by , in manifest order, when the root manifest's [backend.<language>] table names an encoding (the CLI reference describes the table), and is empty otherwise. No flag sets an option.
• artifactBase is the name ridl gives this package's files: the package name, or the file stem in single-file mode. A plugin that lays its output out another way can ignore it.
• generatedMarker is the line that marks a generated file as generated, without a comment token. The host composes it. See the marker below.
• header is the project's file header from [codegen] header-file, without a comment token, or an empty string when the project sets none. Both keys are always present in the JSON, so an empty header is "header": "".
• deployment is the deployment section, described below. It is absent when the build selects no deployment.

The marker and the header

A plugin is recommended, not required, to write generatedMarker as the first line of each file it writes that can hold a comment, as a comment in that file's syntax, and then header, one comment line per header line, then one blank line. The marker comes first because rustfmt looks for @generated only in the first 5 lines of a file. A plugin that writes in Rust can call ridl_ir::codegen::comment_preamble(marker, header, "//"), which returns that block; a plugin in another language writes the same layout, with an empty header line as the bare comment token and no trailing space. A file that cannot hold a comment, such as JSON, carries neither. Where the key comes from, and how a project sets the header, is in the CLI reference.

The documentation fields

Every message of the model that carries a doc carries four more fields beside it: Declaration, Field, EnumValue, Arm, Interface, Interaction, Service and Param. A plugin that writes doc comments reads them there:

• links — the resolved links of doc, in source order. Each is a DocLink: text is the link text as written, offset and len are the link's byte position in doc, and target is the item it names. Replace the len bytes at each offset with the plugin's link syntax, from the last link to the first, so that each earlier offset stays valid.
• see — the @see targets, in source order, as DocLinks whose offset and len are 0.
• since — the @since versions, in source order.
• rules — the rules of the item. A Rule has a text, the line the editor's hover shows for it, and a kind, a oneof of the structured fields: range, step, unit, length, pattern, collection_bound, timing, response_bound, errors or contract (a require or an ensure clause). rules is filled on a Declaration, an Interaction, a Field and a Param, and is empty on the other carriers.

DocLink.target is a qualified name, pkg.Name with an optional .member, not a spelling in any target language. A plugin maps it to its own path with its own name transform (ADR-0016). The in-tree backends write a target that has no item in their output as a code span of the qualified name, so that the output holds no link that does not resolve.

A new kind of rule is a new oneof member, which is an additive change. A plugin renders Rule.text for a kind it does not know, so its docs stay complete: ridl_ir::codegen::request_from_json drops a member it does not know and keeps text. Param carries the parameter's own doc as well. How the in-tree backends render these fields is in Documentation in the generated code.

The deployment section

The deployment section holds the facts of one deployment of the workspace's system that a plugin needs to lay out memory: the regions, one per catalog, with each catalog's hash and interfaces; the instances; one channel per member and producer instance, with its consumer links; and the transport bindings. Every request of one build carries the same section. The design record, §7, states what each part holds, its order, and the rules behind each value.

--deployment NAME selects the deployment. Without the flag, the request carries the deployment when the system declares exactly one, and none when it declares several or the workspace has no system. The CLI reference states every case.

Each consumer link states its crossing and the encoding that follows from the crossing: FlatBuffers on the same machine, proto3 to a different machine or off-board. One consumer link of the warning event in examples/cabin:

jq '.deployment.channels[1].consumers[0]' request.json

{
  "component": "veh.cabin.Panel",
  "instance": "Unit",
  "machine": "Hpc",
  "crossing": "CROSSING_SAME_MACHINE",
  "encoding": "ENCODING_FLATBUFFERS",
  "depth": {
    "value": 10,
    "source": "VALUE_SOURCE_DERIVED"
  },
  "slotsSource": "VALUE_SOURCE_UNSPECIFIED",
  "budgetSource": "VALUE_SOURCE_UNSPECIFIED"
}

Where a sizing value comes from. An event's depth, and a command's or a query's slots and budget, each come with a source, written in the JSON as VALUE_SOURCE_<NAME>:

A source of UNSPECIFIED comes with an absent value: a field the member's kind does not use, such as slots on an event link, or a budget that nothing declares. The design record, §7, lists every case in which a depth is underivable. The rsdl reference §5 states the sizing keys, and Describing a system shows them in use.

Sizes

The model states the maximum encoded size of every payload, of every command and query request, and of every query reply, once per wire encoding: proto3, FlatBuffers and podbuf. Each is bounded with a byte count, unbounded with a cause (for FlatBuffers only), or absent with a cause. The model also sums them: Interaction.reservation is the memory a call table reserves for one member, and Interface.table_budget (the key tableBudget) is the memory for the whole interface, each as a byte count or as unsized, naming the first payload or member that has no bounded size. Each Declaration carries two more sizes. proto3 is the proto3 size state of the declaration's root message — its own message for a struct or a union, its <Name>Box message for a named scalar, an enum and an enum set. podbuf is the podbuf size state of the declaration as a payload root, the bound ridl_ir::projection::podbuf::max_size computes. A constant has neither. A codec reads them as the declaration's largest encoded size, as the Rust backend does.

A plugin reads these sizes; it does not compute them. The sizes of the warning event's payload in examples/cabin, and its reservation:

jq '.model.interfaces[0].slots[1].interaction.event.payload.sizes' request.json

{
  "proto3": {
    "bounded": 8
  },
  "flatbuffers": {
    "bounded": 60
  },
  "podbuf": {
    "bounded": 16
  }
}

jq '.model.interfaces[0].slots[1].interaction.reservation' request.json

{
  "proto3": {
    "bytes": "8"
  },
  "flatbuffers": {
    "bytes": "60"
  },
  "podbuf": {
    "bytes": "16"
  }
}

A reservation is a 64-bit integer, so its byte count is a string. The rules behind each state and each sum are in the catalog descriptor record, "The size states". A plugin that sizes a socket message adds the frame header and the envelope of the transport binding to the payload bound; the deployment section's bindings list carries those values: the websocket row of the frame specification §11.1, a data-plane frame header of at most 20 bytes and an envelope of 16 bytes. A test of ridl-transport-ws checks that row against the frames its codec writes.

The podbuf layout

Model.podbuf holds the layout of every podbuf head of the package, so that a plugin that writes podbuf code never computes the layout law. Each head lists its fields with the offset, the size, the alignment and the form of each, the flag bit of an optional field, and the unused byte runs. A form says what the bytes are: an integer, a float, an enum, an inline head (an index into podbuf.heads), an exact-length array, or a descriptor to the tail with the element type, the stride and the bounds. A union head lists the head of each arm. A struct, union or tuple that cannot be laid out is listed in podbuf.refused with its cause, and no head is written for it. The codegen plugin record, "The podbuf projection" gives the order of the heads and the meaning of each field.

The catalog hash

The model's catalog holds the unit name, in the field package, and the catalog hash, a 32-byte SHA-256 over the interfaces of every source package of the unit and every declaration they reach (ADR-0014 decision 15). The field keeps its name package for the generated accessors of every plugin; its value is the unit's name, which is CatalogRef.name. In the JSON, the hash is base64. Each region of the deployment section carries the same hash for its catalog.

Embed the name and the hash in the generated code, and check them when the generated code binds to a port. The Rust face does this: each generated interface carries its catalog's name and hash, and binding to a port whose catalog differs panics with a message that names both catalogs (ADR-0023 decision 8; the face's catalog check). Code generated from one contract then refuses a port of another contract when it binds, instead of exchanging bytes that one side reads wrongly.

A provisional interface number. An interface that has no entry in its unit's interfaces.lock has a provisional number, and the model marks it provisional. A provisional number can change: adding an interface before it in the source can move it, and recording it with ridl lock changes the catalog hash, because the hash covers each interface's number and its provisional flag. A provisional number is fine during development. Never rely on it across parties that are built separately; run ridl lock and commit interfaces.lock first. ridl diff reports the number that ridl lock freezes as interface_frozen, and a provisional number that moves as interface_number_changed.

The catalog descriptor

ridl build --emit catalog writes <unit>.catalog.binfb, a FlatBuffers file of a unit's interfaces, their members, their payload size bounds and the catalog hash. The unit is the set of source packages that one ridl.toml declares, and the hash is computed over that unit. One file is written per unit that declares an interface or a service with an inline body; a unit that declares only types writes none. It is for a run-time engine that is not compiled against the unit and reads the file when a party attaches; no such engine is in this repository. ridl describe prints it as JSON.

A plugin does not read the catalog descriptor: the model carries the same facts. The chapter The catalog descriptor describes the file for its readers, and the catalog descriptor record gives its byte-level details.

A system descriptor, a file per deployment, is not built (catalog descriptor record, "Not built"). The request's deployment section carries those facts to a plugin at build time.

What is not available yet

• podbuf on a consumer link. Every payload has a podbuf size state and the model carries the podbuf layout (see "The podbuf layout" above), but no consumer link carries ENCODING_PODBUF: no rsdl fact selects it.
• Members whose depth or size cannot be derived. An event's depth is absent with the source UNDERIVABLE when its timing gives no bound. The build warns with RSDL-806 when a consumer link consumes such an event with no declared depth (see Lints); it does not warn when no link consumes the event (driftsys/ridl#735). A stream payload, a request of zero or of several parameters, and an inline T | E reply have no size in any encoding, so the reservation of such a member is unsized. No single issue tracks these cases; each is recorded in the design record, §7, and in the catalog descriptor record.

Examples

• crates/ridlc-gen-model/src/main.rs is a complete plugin in one file of under 80 lines, its module comment included. It reads the request, refuses an unknown schema, writes the model back as one file, and writes the response.
• crates/ridlc/tests/layout.rs holds a test plugin that reads the deployment section. It computes the byte layout of each region of the examples/cabin deployment and the maximum size of each message that crosses a socket, from the request alone. Its module comment states the layout rule, which belongs to the test and not to the toolchain. It runs in process, through the same Backend trait the in-tree backends implement.
• driftsys/ridlc-gen-kotlin is a plugin outside this repository, written in Kotlin. It runs through ridl build --plugin kotlin and generates Kotlin value objects, codecs and faces from the model.

CLI reference

Two command-line binaries ship from this repository: ridl, the porcelain facade, and ridlc, the plumbing compiler underneath it. ridl hosts the language server as the ridl lsp subcommand and the Model Context Protocol server as ridl mcp, both over stdio (see What is built). The VS Code extension spawns ridl lsp. Build both with:

cargo build --release

as Getting started describes. This page assumes target/release/ridl and target/release/ridlc are on your PATH, or called by path.

Only typl and ridl have a toolchain — see What is built. Every command and transcript below runs against a workspace built from those two layers; rxdl, rmdl, and rsdl accept no command here.

Every synopsis and transcript on this page is the literal output of the binaries built from this repository, run against constructed fixtures. The fixtures themselves are not reproduced here — this page documents command behavior, not how to write a .ridl file, and a fixture built for one transcript is often a one-line edit of the fixture built for the transcript before it. Getting started is the tutorial that shows complete, worked files; treat a transcript below as a faithful record of what the tool printed against some input shaped as described, not as a listing you can paste in whole. Every exit code stated below was observed by running the command and reading its exit status, not read out of a help string or a specification.

ridl --version and its short form ridl -V (and ridlc --version) print the binary's own name and version and exit 0:

ridl --version

ridl X.Y.Z

X.Y.Z stands for the build's version: the crate version for a local build, or the release tag when the release workflow sets RIDL_BUILD_VERSION. The version does not name a commit, so it cannot answer "which commit is this" — recorded as a known gap in ADR-0010 decision 8, which also records a deferred fix.

ridl

ridl --help

The RIDL toolchain

Usage: ridl <COMMAND>

Commands:
  check     Type-check a file, package, or workspace (defaults to the current directory)
  baseline  Publish the current workspace as a baseline: one `<pkg-name>.ir.json` snapshot per package and one `<unit>.catalogs` file per unit with an interface, written to `.ridl/baseline/` at the workspace root
  build     Compile to the selected artifacts (defaults to the current directory)
  test      Run the property suite over a workspace: the range self-corpora and the contract-clause sampling (ridl §13). Exit 0 when every run passes, 1 on a self-corpus failure or an evaluation error, 2 on a compile error
  fmt       Reformat `.typl`, `.ridl` and `.rsdl` files in place (defaults to the current directory)
  diff      Compare two IR snapshots or source trees and classify the change: exit 0 compatible or identical, 1 breaking, 2 error
  lock      Allocate a number to every interface that has none and write each unit's `interfaces.lock`; with `--rename` or `--retire`, rewrite one unit's entries in place instead. Exit 0 when the file is written or nothing changes, 1 on a diagnostic error, 2 on a bad flag or a path or I/O failure. `ridl lock merge` is the git merge driver for the file
  lsp       Run the language server over stdio: exit 0 after `shutdown` then `exit`, 1 when the client ends the session without `shutdown`, 2 on a transport error. Editors spawn this. Stdio is the only transport
  mcp       Run the MCP server over stdio for an agent host: exit 0 on a clean shutdown, 2 on a transport error. It takes no flag of its own
  init      Scaffold a new unit in a directory that exists (defaults to the current directory): a package, or with `--workspace` a workspace and one member. Writes `ridl.toml` and one source file, and exits 2 without writing anything when a target file exists, the name is not a legal package name or holds a reserved word, or a `ridl.toml` above or below the directory would make a manifest inside a unit (MANI-013)
  new       Create a directory, with its parents, and scaffold a new unit in it, as `ridl init` does. Exits 2 without writing anything when the path exists
  describe  Print a catalog descriptor as strict JSON, after verifying it
  vendor    Copy every remote unit of the workspace's `[imports]` into `vendor/` at the manifest root, so a `--frozen` build needs no network and no cache. Every directory in `vendor/` that no `[imports]` key names is removed; files and hidden entries are left. Exit 0 when `vendor/` was written or there was nothing to change, 1 on a diagnostic error (`vendor/` is left untouched; `ridl.lock` may be updated), 2 on a missing or unreadable path, a fetch failure, or an I/O failure. With `--check`, compare `vendor/` with the imports and `ridl.lock` instead, writing nothing
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Running ridl with no subcommand at all prints this same text to stderr and exits 2; ridl --help prints it to stdout and exits 0 — the two routes carry identical text but are not interchangeable in a script that checks the exit code or reads the right stream.

ridl lsp and ridl mcp are the two stdio servers this binary hosts — the language server an editor drives, and the Model Context Protocol server an agent drives. ridl mcp takes no argument or flag; ridl lsp takes only the two flags editor clients pass, which change nothing. Each is documented in its own section below, ridl lsp and ridl mcp, and each exits 0 when the client shuts it down and 2 when the transport ends before the handshake or otherwise fails.

ridl check

ridl check --help

Type-check a file, package, or workspace (defaults to the current directory)

Usage: ridl check [OPTIONS] [PATH]

Arguments:
  [PATH]  [default: .]

Options:
      --frozen               Verify remote imports against `ridl.lock` without fetching or regenerating it (CI mode, ADR-0002 §7)
      --baseline <DIR|FILE>  Compare the checked workspace against a published baseline — a directory of `.ir.json` snapshots or one snapshot file — and warn (RIDL-407) on every interaction whose ordinal moved and every struct field or union arm change `ridl diff` gates on that concerns an ordinal: a member inserted, one removed, one moved in an edit that added or removed no member, and one appended beside such a change or to a result union. An append that is breaking only for its field's type moves no ordinal and draws no warning. Without the flag, `.ridl/baseline/` at the workspace root is used when it exists
      --format <FORMAT>      Output format for the report: text renders to stderr (the default); json goes to stdout instead — see the CLI reference (docs/book/cli-reference.md) for its schema; sarif writes one SARIF 2.1.0 log to stdout, for code-scanning viewers [default: text] [possible values: text, json, sarif]
  -h, --help                 Print help

PATH is a .typl, .ridl or .rsdl file, a package directory, or a workspace root, and defaults to the current directory. A .rxdl or .rmdl file is refused as PATH when no ridl.toml is at or above it, as the next paragraph says. A PATH inside a workspace member loads the whole workspace whose members lists the member (ADR-0002 §4): the root's [lints], the [defaults] keys and [imports] apply, imports of sibling members resolve, and the report holds only the diagnostics of files under the member. ridl build on a member also writes the whole workspace. An error in another member makes it exit 1 with one error that says so; it then writes nothing, or, for an RSDL-7xx error, leaves that deployment out of the system. The workspace root's .ridl/baseline/ and ridl.lock serve a member entry too. --frozen is the same flag ridlc check --frozen documents, forwarded unchanged; the two commands share one implementation and render byte-identical diagnostics on the same input. It now carries this description word for word under ridl too — before ADR-0010, ridl check --help rendered it with a blank line where the description belongs.

The loader compiles the .typl, .ridl and .rsdl files of a package directory. A .rxdl or .rmdl file there is not compiled, because the rxdl and rmdl profiles have no implementation (driftsys/ridl#68): each one draws the warning RIDL-417 (unsupported-source-file) on the file itself, and its declarations are not in the build. A bare .rxdl or .rmdl file given as the entry with no ridl.toml at or above it is refused: every command that loads source through the loader, such as ridl check, ridl build and ridl diff, exits 2 with an error that names the extension as unsupported, and compiles nothing.

It writes ~/.ridl/cache and ridl.lock, but only when the manifest declares [imports]. ridl check loads, resolves, and checks the workspace. When the checked-out manifest (or a package in it) has an [imports] table, it also materializes each remote unit. It reads the unit from vendor/<key>/ at the manifest root when that directory exists and ridl.lock pins a tree for the unit's URL (see ridl vendor); otherwise from ~/.ridl/cache (ADR-0002 §7, indexed by URL and by the fetched artifact's SHA-256) or, on a cache miss outside --frozen, fetches it. Where ridl.lock pins no tree for the unit, the cache or the fetch pins it first, and a vendored directory, if present, is then verified against that pin and read in place of the cache entry. It verifies the tree hash of the tree it read, which for a vendored tree that no longer matches is MANI-107, with a message that names ridl vendor; loads the unit as a read-only dependency; and on a clean run regenerates ridl.lock at the workspace root with both hashes. A remote unit's errors fail the check, and its warnings are not shown. Every other fixture on this page has no [imports], so none of them reach either write. The transcript below is an illustration, not a recorded run: the URL names a local HTTP stub, and the two hashes are placeholders that stand for the values a run computes.

ridl check && cat ridl.lock

# ridl.lock — generated by ridlc; do not edit by hand.
# Regenerated on every successful resolution (ADR-0002 §7).

[entries."http://127.0.0.1:8934/remotepkg.tar"]
sha256 = "<the SHA-256 of the fetched artifact>"
tree = "<the hash of the unpacked tree>"

ridl build and ridl baseline materialize remote units the same way, and ridl build generates their packages beside the workspace's own. No IR dump, catalog, baseline snapshot or ridl lock entry includes a remote unit.

--frozen verifies against the existing ridl.lock instead of fetching or regenerating it, exactly as its description says: with no ridl.lock on disk yet, ridl check --frozen over the same workspace fails closed (MANI-103, exit 1) rather than writing one. A ridl.lock written before the tree hash existed has no tree; under --frozen that is MANI-108, and a run without --frozen adds the hash.

ridl lock, ridl test, ridl diff, ridl lsp and ridl mcp read vendor/<key>/ and then the cache the way --frozen does: they never fetch and never write ridl.lock. In a fresh clone, run ridl check once first, or run ridl vendor; otherwise these commands report MANI-103 (no ridl.lock entry) or MANI-104 (the pin is neither in vendor/ nor in the cache). A ridl.lock written before the tree hash existed gives them MANI-108 too, and the same ridl check adds the hash.

Exit codes. 0 when nothing is wrong — a clean run prints nothing at all, to either stream. 1 when a diagnostic is an error, for example a range whose minimum exceeds its maximum:

ridl check

error[TYPL-104]: range minimum 250 is greater than maximum 0
  ┌─ ./demo.ridl:3:19
  │
3 │ type Speed : km/h [250.0..0.0 step 0.5]
  │                   ^^^^^^^^^^^^^^^^^^^^^

The same run with --format json prints the JSON diagnostic contract, also produced by ridl_core::diag::to_json, as a bare array:

ridl check --format json

[
  {
    "code": "TYPL-104",
    "severity": "error",
    "message": "range minimum 250 is greater than maximum 0",
    "span": {
      "path": "./demo.ridl",
      "start": {
        "line": 3,
        "column": 19
      },
      "end": {
        "line": 3,
        "column": 40
      }
    },
    "labels": [],
    "fixes": []
  }
]

A diagnostic whose code is a lint carries one more field, lint, which holds the lint name, for example "lint": "unbounded-float" next to "code": "TYPL-102". The field is absent for a code that is not a lint and for a diagnostic with no code. severity is always the effective severity, after the levels in the [lints] table of ridl.toml are applied, so a lint set to deny reports "severity": "error" and a lint set to allow is not in the array. The text report names the lint in a note after the snippet (= lint: ...), as the examples below show.

--format sarif writes one SARIF 2.1.0 log to stdout, for code-scanning viewers such as GitHub code scanning. The log holds one run. Its tool.driver.rules lists every catalogue code, errors included, with the lint name as the rule name when the code is a lint and the default level as defaultConfiguration.level. Each result has the code as its ruleId, the effective level (error, warning, or note for an info), the message, and one location; each label becomes a related location. Columns count Unicode code points (columnKind is unicodeCodePoints). The log carries no fix-its, which the JSON output carries, and no helpUri. A diagnostic with no source file, such as a lockfile or remote-fetch diagnostic (MANI-1xx), has no location. An uncoded diagnostic has no ruleId and no ruleIndex. An artifact URI is relative to the current working directory, with / separators and every segment percent-encoded; it carries uriBaseId %SRCROOT%, which the run's originalUriBaseIds resolves to the working directory as a file:// URI. A file outside the working directory is an absolute file:// URI with no uriBaseId. The comparison is lexical, not through the filesystem: a relative path is joined onto the working directory, and an absolute path is compared with the working directory as the operating system spells it, so an absolute path that reaches the working directory through a symbolic link (/tmp on macOS, for example) counts as outside it. Run ridl check --format sarif from the repository root, with the path to check given relative to it, so that every URI is relative to the root, which is what a code-scanning upload expects. The exit code is the same as for the other formats.

2 when the workspace itself cannot be found:

ridl check

error: no `ridl.toml` found at or above `.`

An explicit --baseline naming a path that does not exist is the same exit 2, for the same reason — asking for a baseline that is not there is a mistake worth reporting, while a missing default baseline is silently skipped:

ridl check --baseline ./nope

error: the baseline `./nope` does not exist

A baseline directory that holds IR artifacts but no .ir.json snapshot — named with --baseline or auto-discovered at .ridl/baseline/ — is also exit 2, with a message naming an artifact it found: a baseline stays .ir.json (ADR-0014 decision 5), so such a directory is a baseline in a refused encoding, not the silently skipped "no baseline published yet" state. An empty directory is still that silent state when auto-discovered; named explicitly with --baseline, it is a different refusal (below). A snapshot-named entry inside the directory that cannot be stat'ed — a symlink to a file that is gone — is exit 2 under either, naming the entry, because skipping it would read the directory as one snapshot short.

So is a directory whose .ir.json snapshots sit one level below it rather than inside it — --baseline .ridl where .ridl/baseline was meant. The message names the subdirectory it found and gives the path to pass instead. Snapshots are read from one directory and never from the directories below it, so a directory of this shape is a path aimed one level too high, not a layout to descend into.

An explicit --baseline that yields no snapshot at all — an empty directory, or one whose snapshots sit two or more levels down rather than one — is the same exit 2: the message names the directory, says to point --baseline at the directory that holds the snapshots (ridl baseline publishes them to .ridl/baseline/ at the workspace root), and only then offers ridl baseline --out <directory> for publishing a first baseline into that directory. The offer is left out when the directory is a source tree — it holds a ridl.toml, or a .typl, .ridl or .rsdl file, directly inside it — since publishing a baseline there would write snapshots next to the sources. Auto-discovery asserts nothing about a baseline being present, so a .ridl/baseline/ directory found this way, empty or absent, keeps the silent skip the two paragraphs above do not touch.

The baseline desk check. With .ridl/baseline/ present at the workspace root — written by ridl baseline — ridl check compares the workspace against it and warns (RIDL-407) on every interaction whose declaration order moved, and every struct field or union arm change ridl diff gates on that concerns an ordinal. At its default level the warning does not change the exit code; RIDL-407 is the lint ordinal-changed, so ordinal-changed = "deny" in [lints] reports it as an error, which makes the run exit 1, and ordinal-changed = "allow" removes it. The warning for a field or arm follows the verdict the gate reads, so the two agree: a member inserted, one removed, one moved in an edit that added or removed no member, and one appended beside such a change each draw one warning, and an append alone draws none — not even one the gate reports breaking because the field's type excludes 0 (driftsys/ridl#598) — except an arm added to a result union, whose arms are its transport identity (ADR-0008 decision 4). A removal draws one whether or not a reserved tombstone keeps the slot, because the diff does not yet read a composite body's reserved entries. The diff reports no reorder beside an addition or a removal, so the warning for the added or removed member names the siblings whose ordinal changed. Reordering two events in a published interface:

ridl check

warning[RIDL-407]: `doorOpened` has moved in `VehicleStatus` since the published baseline (position 1 there, position 2 here). Declaration order is the wire identity of an interaction (ridl §11), so a consumer built against the baseline would now bind this slot to a different interaction — put the declarations back in the baseline's order and add new ones at the end
  ┌─ ./demo.ridl:7:3
  │
7 │   event doorOpened : DoorState @[100ms..1s]
  │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  │
  = lint: `ordinal-changed` (set its level in `[lints]` in ridl.toml)

warning[RIDL-407]: `doorClosed` has moved in `VehicleStatus` since the published baseline (position 2 there, position 1 here). Declaration order is the wire identity of an interaction (ridl §11), so a consumer built against the baseline would now bind this slot to a different interaction — put the declarations back in the baseline's order and add new ones at the end
  ┌─ ./demo.ridl:6:3
  │
6 │   event doorClosed : DoorState @[100ms..1s]
  │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  │
  = lint: `ordinal-changed` (set its level in `[lints]` in ridl.toml)

That run exits 0: two RIDL-407 warnings and an otherwise clean compile stay clean. The desk check runs only after a compile with no error diagnostic other than RIDL-409 — a live interfaces.lock entry with no declaration, which leaves nothing out of the IR the desk check compares — and other than a lint raised to deny. A workspace with any other error draws no RIDL-407 warning in addition to that error: it exits 1, exactly as it would with no baseline present. Entered at a workspace member, the run reports only the diagnostics of files under the member (ADR-0026 decision 10), and the desk check compares the whole workspace: an error in another member is not reported, the desk check does not run, and the run exits 0, exactly as it would with no baseline present. Run ridl check at the workspace root to see that error and, once it is fixed, the member's RIDL-407 warnings. A workspace whose only errors are RIDL-409 still exits 1, and the desk check runs over it: when exactly one declaration without an entry has the published shape of the orphan entry's interface, the desk check adds a label to that RIDL-409 naming the ridl lock --rename command to run. A lint raised to deny in [lints] is an error for the exit code but does not stop the desk check: the run reports the denied lint and the RIDL-407 warnings together, and exits 1.

ridl baseline

ridl baseline --help

Publish the current workspace as a baseline: one `<pkg-name>.ir.json` snapshot per package and one `<unit>.catalogs` file per unit with an interface, written to `.ridl/baseline/` at the workspace root

Usage: ridl baseline [OPTIONS] [PATH]

Arguments:
  [PATH]  [default: .]

Options:
      --out <DIR>  Write the snapshots and the catalog files here instead of `.ridl/baseline/`
  -h, --help       Print help

It writes one <package-name>.ir.json file per package in the workspace, under .ridl/baseline/ at the workspace root or under --out when given — and, exactly like ridl check, ridl.lock at the workspace root when the manifest declares [imports] (ridl baseline builds through ridlc build, non-frozen, so the same materialization step runs). Publishing the snapshots is wholesale: the target directory ends up holding exactly the snapshots the workspace declares now. Nothing else in that directory is touched except the *.catalogs files, which publication replaces as the catalog files below describes. The snapshots stay one per source package; ridl diff groups them by unit when it compares them. The workspace's interface numbers must be recorded first: a provisional number is refused (RIDL-411, under the publication gate below), so a package with interfaces runs plain ridl lock before its first publication. A two-member workspace with no [imports], its locks written, publishes two files and no ridl.lock:

ridl baseline && find .ridl/baseline -type f | sort

.ridl/baseline/veh.cluster.ir.json
.ridl/baseline/veh.common.ir.json

The catalog files. Beside the snapshots, ridl baseline writes one <unit>.catalogs file per unit that has at least one interface shape, named after the unit's manifest name, in the same directory. A file is a text file: a first line that starts with #, then one catalog hash per line as 64 lowercase hexadecimal characters, newest first. An empty line and a line that starts with # are skipped, and a hash is listed once. A line may end with CRLF, as a checkout with core.autocrlf writes it; a line with any other padding, such as a space, is refused. The first hash is the catalog hash of the baseline being published, computed as ridl build --emit catalog computes it. The hashes that follow are the ones of the file being replaced, copied as they are and never recomputed from a snapshot. They are carried over when ridl diff's classifier, scoped to the unit, judges the change from the replaced snapshots to the fresh ones compatible or identical, and when the new hash is the first hash of the replaced file: the catalog did not change, so every hash the file lists still applies, whatever the verdict. The scope is the unit's own source packages and every declaration its interfaces reach, in the unit or in another one, so a breaking change in a package that the unit does not reach leaves the unit's chain as it was. A breaking change that changes the catalog restarts the chain: the file then holds the one new hash. The file being replaced is carried only when its first hash is the hash recomputed from the snapshots published beside it; a file that does not describe those snapshots, as a partially hand-edited baseline leaves behind, restarts the chain instead of carrying a hash that may reach past a breaking change. A unit with no published snapshot, or with no <unit>.catalogs file in the replaced baseline, also starts a chain with the one new hash, and a file left under the name of a unit that had no published snapshot is not carried, nor read. The file of a unit with a published snapshot that cannot be read, or has a line that is neither a comment nor a hash, or lists the same hash twice, stops the publication with exit 2: the message names the file and the line, and says to repair the file or remove it to start the unit's chain again.

Publication replaces the files in this order, so that an interrupted run never leaves a history beside a snapshot it does not describe: every published *.catalogs file is removed, then the fresh snapshots move in, then the fresh *.catalogs files move in, and last the snapshots of packages the workspace no longer declares are removed. A file left by a unit that no longer has an interface shape is removed by the first step and not written again. The histories are written only after the publication gate below has passed, so a refused run leaves every published file as it was.

The publication gate. Before replacing the published snapshots, ridl baseline compares the snapshot it is about to publish against the one already there, and refuses to replace it when, in an interface body both declare, the replacement breaks the tombstone rule of ridl §11 — RIDL-408, exit 1, the published snapshots left as they were (the compile has already run, so ridl.lock is written as on any other run). The refusal covers four shapes: an interaction is gone from the source with no reserved line at all; the source retires it with a reserved line, but at an ordinal other than the one the interaction held; the baseline already retired the interaction with a reserved line and the source has dropped that line; or the source declares a live interaction under a name the baseline retires. The interface level of the gate is the lock's: an interface whose number is provisional — a declaration with no entry in the unit's interfaces.lock — is refused (RIDL-411, exit 1, nothing published), on a first publication as on a replacement, until plain ridl lock records the number; and a number the published baseline holds that the fresh snapshot neither carries nor retires is refused too (RIDL-412). That covers a lock line deleted by hand, since a live entry with no declaration already fails the build with RIDL-409. It also covers a package deleted, without retiring its numbers, from a unit that still has other packages, and a whole unit deleted from the workspace. For a package the message names the line to restore in the unit's interfaces.lock. For a whole unit the lock left with it, so the message names the deliberate override instead: delete the snapshots of that unit from .ridl/baseline/, so that the next publication holds no number to lose. A published snapshot written before the IR recorded the unit carries no unit; the gate compares it in the unit of the fresh package of the same name, so the migration to one interfaces.lock per unit — delete the per-package lock files, run ridl lock, run ridl baseline — passes RIDL-412 when the unit's new numbering reaches every published number. When it does not, because a legacy lock held retired entries, remove .ridl/baseline/ and run ridl baseline again: a first publication is not compared against a published number, and no flag overrides the gate. A whole service removed from the source is reported by ridl diff as breaking but is not refused here (ridl §17.14), and a named-form service's list is a set the gate does not read. Deleting doorClosed outright, with doorOpened and doorLocked still declared:

ridl baseline

error[RIDL-408]: `doorClosed` is gone from the source but the baseline being replaced still declares it in `VehicleStatus` (ordinal 2). Publishing would free its ordinal for a later interaction to reuse, with nothing left to record that it was ever taken. Retire it in place with `reserved doorClosed`.
  ┌─ ./demo.ridl:3:11
  │
3 │ interface VehicleStatus {
  │           ^^^^^^^^^^^^^

A first publication — the output directory absent, or present and holding no .ir.json snapshot yet — has no published snapshot to compare against, so RIDL-408 and RIDL-412 never refuse it. This is the same empty-directory shape ridl check --baseline refuses when it is named explicitly: ridl check --baseline refuses it because the user named the directory as a baseline to compare against, while ridl baseline --out treats it as a first publication because it is the directory being written. RIDL-411 still refuses a first publication that holds a provisional interface number, because RIDL-411 reads the fresh snapshot alone.

Exit codes. 0 on a clean publish. 1 when a diagnostic is an error, or when the publication gate above refuses the replacement — in both cases the existing baseline is left exactly as it was, because a re-publish must never destroy a good baseline with a broken one:

ridl baseline

error[TYPL-011]: unknown type name `Nope`
  ┌─ ./demo.ridl:4:22
  │
4 │   event doorClosed : Nope @[100ms..1s]
  │                      ^^^^

2 when the workspace itself cannot be found, the same as ridl check, when the output directory cannot be read or written, when a published .ir.json snapshot fails to parse, when two published snapshots declare one package, or when an entry of the output directory named like a snapshot cannot be stat'ed:

ridl baseline /nonexistent/ridl/workspace

error: `/nonexistent/ridl/workspace` does not exist

A published snapshot that cannot be parsed is left untouched rather than silently overwritten: replacing it would destroy whatever ordinal record it held without any report. ridl cannot tell a damaged file from a snapshot that a toolchain with a different IR schema wrote — the reader rejects an unknown field (ADR-0014 decision 14) and a snapshot carries no schema marker — so the message names a remedy for each cause, and neither remedy discards the record unread:

ridl baseline

error: ./.ridl/baseline/veh.cluster.ir.json: the IR snapshot is not valid IR v2 JSON: expected value at line 1 column 1; the file is left as it is, because a record that cannot be read cannot be shown safe to replace. If the file is damaged, restore it from version control or resolve the merge conflict left in it. If a toolchain with a different IR schema wrote it, check the source against it with that toolchain (`ridl check --baseline`), then remove the file and run `ridl baseline` with this one

The same parse error on a ridl diff input, or on a file or directory named with ridl check --baseline, is reported without that remedy: only the published baseline that ridl baseline is about to replace is the record the remedy protects.

Two published snapshots that declare one package are two records of the same ordinals, and the gate has no rule for choosing between them, so it refuses rather than compare against either. Both files are left as they are; the message names the package and both files. Here zz-copy.ir.json is a copy of the published snapshot left beside it:

ridl baseline

error: two published snapshots declare the package `veh.cluster`: `./.ridl/baseline/veh.cluster.ir.json` and `./.ridl/baseline/zz-copy.ir.json`; both files are left as they are, because the gate cannot tell which one is the published record. Remove the copy that is not the published record (restore the directory from version control if unsure), then run `ridl baseline` again

This refusal is ridl baseline's alone: ridl check --baseline and ridl diff read such a directory as a snapshot set, matching packages by name.

An entry of the output directory named like a snapshot whose metadata cannot be read — a symlink to a file that is gone — is also exit 2, naming the entry. Skipping it would read the directory as one snapshot short, which is a first publication to the gate, and the publication would then replace the entry with a snapshot that had dropped the ordinal record. The entry is left as it is. ridl check reports the same entry the same way when it finds it under .ridl/baseline/ by auto-discovery, and so does ridl diff over a directory side:

ridl baseline

error: cannot read the snapshot ./.ridl/baseline/veh.cluster.ir.json: No such file or directory (os error 2)

ridl build

ridl build --help

Compile to the selected artifacts (defaults to the current directory)

Usage: ridl build [OPTIONS] [PATH]

Arguments:
  [PATH]
          [default: .]

Options:
      --out-dir <OUT_DIR>
          [default: out]

      --emit <EMIT>
          Possible values:
          - rust:            Idiomatic Rust source, written to `<base>.rs`
          - ir-json:         The lowered IR v2 as exact-decimal JSON, written to `<base>.ir.json`, and the lowered system to `<pkg.Name>.system.json`
          - ir-text:         The lowered IR v2 as prototext, written to `<base>.ir.txtpb`, and the lowered system to `<pkg.Name>.system.txtpb`
          - ir-binary:       The lowered IR v2 as protobuf binary, written to `<base>.ir.binpb`, and the lowered system to `<pkg.Name>.system.binpb`
          - typescript:      Idiomatic TypeScript source, written to `<base>.ts`, and the codec module `<base>.codec.ts` with `[backend.typescript] codec = true`
          - proto:           The proto3 schema, written to `<base>.proto`
          - flatbuffers:     The FlatBuffers schema, written to `<base>.fbs`
          - podbuf:          The podbuf C header, written to `<base>.h`
          - codegen-model:   The lowered codegen model (`ridl.codegen.v1`) as canonical protobuf JSON, written to `<base>.codegen.json`
          - codegen-request: The whole codegen request a build hands a backend, as canonical protobuf JSON, written to `<base>.codegen-request.json`
          - catalog:         The catalog descriptor an engine reads, written to `<unit>.catalog.binfb` for every unit that declares an interface or a service with an inline body: a FlatBuffers file of the unit's interfaces, their members and their catalog hash
          
          [default: rust]

      --plugin <LANGUAGE[=PATH]>
          A codegen plugin to run beside the emits, once per package: `<LANGUAGE>` runs `ridlc-gen-<LANGUAGE>` from PATH, `<LANGUAGE>=<PATH>` runs the executable at PATH. Repeatable

      --plugin-timeout <SECONDS>
          Seconds a plugin may run per package before it is killed
          
          [default: 60]

      --frozen
          Verify remote imports against `ridl.lock` without fetching or regenerating it (CI mode, ADR-0002 §7)

      --deployment <NAME>
          The deployment to carry in each codegen request. With one deployment in the workspace it is selected without this flag; with several, none is carried unless named

  -h, --help
          Print help (see a summary with '-h')

--emit accepts a comma-separated list, so one invocation can write several targets. --frozen is the same flag as on ridl check: it is ridlc build --frozen, documented word for word since ADR-0010.

--deployment NAME picks the deployment of the workspace's system that every codegen request carries. Without it, the request carries the deployment when the system declares exactly one, and none when it declares several or the workspace has no system. A single declared deployment that an RSDL-7xx error removed from the system is not carried either: the build reports that error and exits 1. A NAME that the system does not declare exits 2 and names the deployments it does declare, unless the build already has an error of its own: that error takes precedence, and the build reports it and exits 1. When no name can be right, the message says which reason it is — the workspace declares no system, or the system declares no deployment. A deployment that an RSDL-7xx error removed from the system is not unknown either: the build reports that error and exits 1.

The compatible catalogs. When the build writes a catalog descriptor or generates code, ridl build reads .ridl/baseline/ at the workspace root, as ridl check finds it, and writes into the unit's descriptor and into the catalog.compatible field of the unit's codegen model the earlier catalog hashes it judges compatible with the current catalog. The list comes from the unit's <unit>.catalogs file (see ridl baseline), in the file's order, newest first, and it never holds the current catalog's own hash. It is empty when the workspace has no baseline directory or the directory holds no .ir.json snapshot, when the baseline holds no package of the unit, when the unit has no <unit>.catalogs file (or the baseline has none at all), and when ridl diff's classifier, scoped to the unit, judges the change from the baseline to the tree breaking and the current catalog hash is not the file's first hash. When the two hashes are equal the catalog did not change, and the list holds the file's other hashes whatever the verdict. The file is used at all only when its first hash is the hash recomputed from the baseline's own snapshots of the unit; a file that does not describe those snapshots gives an empty list. The recorded file is not changed by the build. An IR dump reads no baseline. A baseline with at least one <unit>.catalogs file that cannot be loaded, or a <unit>.catalogs file that cannot be read, is exit 2; a baseline with no <unit>.catalogs file is not loaded. A compile with an error diagnostic gets no list, and its baseline is not read. When the workspace names [imports] and a list is computed, the build prints a note on stderr that a unit's list covers the workspace's own packages only.

rust is a language backend, and it writes the whole generated surface of a package in one file: the domain types (a struct, an enum, an enum set, a union and a named scalar, each with its typl constraints enforced at construction) always, and, when [backend.rust] encodings in the manifest names flatbuffers or proto3, the codec of each encoding named — encode, verify, decode and a MAX_SIZE bound — the interaction descriptors, with one size table per encoding, and the interaction face. With no encodings list the file holds the types only. Each interface gets the parts its own interactions need: a Client for the consumer side when it carries any interaction at all; a Publisher for the producer side when it carries a signal or an event; and a Provider trait the application implements plus a serve function whose future settles the claims waiting on a port, when it carries a command or a query; and, when it carries an event, a command or a query, a blocking module under the crate's std feature, on by default, holding the same Client, and the same serve when there is one, as blocking calls with a timeout, each waiting call ridl_rt::task::block_on over the async form. So a signal-only interface gets a Client and a Publisher and nothing to settle with and nothing to block on, a command-only interface gets a Client, a Provider, a serve and a blocking module and no Publisher, and an interface carrying only fixed declarations gets no face module at all, and neither does an internal interface (the design record gives the rule). Beside the per-package files it writes a lib.rs crate root and a Cargo.toml naming ridl-rt with the encoding's feature, and with ridl-rt/std behind the crate's own std. Using the generated Rust code shows how a program uses the crate, and lists its Cargo features.

Generated files are marked. The .rs, .ts, .proto and .fbs files, and the lib.rs and Cargo.toml of the crate root, begin with a line comment that says the file is generated:

// @generated by ridl from package veh.cabin. Do not edit.

veh.cabin is the dotted package name, also in single-file mode, where it is the package the file declares and not the file stem. The lib.rs and Cargo.toml of a standalone package build name that package in the same way. Those of a workspace build belong to no one package, so their line reads @generated by ridl. Do not edit.. Cargo.toml uses # as the comment token. The marker is the first line because rustfmt looks for @generated only in the first 5 lines of a file. It carries no version and no timestamp, so a regeneration with the same inputs gives the same bytes. The TypeScript file has /* eslint-disable */ after the comment block. The IR dumps (JSON, prototext and binary), the <base>.codegen.json file and the <unit>.catalog.binfb file carry no marker.

A licence header goes after the marker. [codegen] header-file in the workspace root's ridl.toml (or in the ridl.toml of a standalone package) names a text file, and ridl build writes its lines after the marker in every file that carries one, then one blank line:

[codegen]
header-file = "LICENSE-HEADER.txt"

The path is relative to the manifest that declares it. The file holds plain text without comment tokens, and each target gets its own comment syntax. ridl accepts CRLF line ends and a lone CR as a line break, removes trailing whitespace from each line and drops leading and trailing blank lines, so a file with no text left means no header. A blank line inside the text becomes a bare comment token. Single-file mode has no manifest and writes no header. MANI-011 is an error when the file cannot be read, when it is not UTF-8, and when it contains a control character, which means a C0, DEL or C1 character (U+0085 included), U+2028 or U+2029, other than a tab and a line break; ridl check reports it too. MANI-012 is an error when the manifest of a workspace member sets the key: only the root sets it. MANI-013 is an error when a ridl.toml sits inside the tree of a unit, and MANI-014 is an error when two units declare the same source package.

A build overwrites a lib.rs or Cargo.toml in the output directory only when the file begins with this marker, or with the marker an earlier release wrote (// Generated by ridlc. Do not edit. and # Generated by ridlc. Do not edit.). Any other file is taken to be hand-written and is not touched.

Mark the output in version control. ridl build does not write a .gitattributes file. To collapse the generated files in review, add a line such as this one, adapted to your output directory:

generated/** linguist-generated=true

The crate root allows two lints. The emitted lib.rs carries #![allow(clippy::derivable_impls, clippy::module_inception)], after the attribute that makes the crate no_std and before the line that links alloc under the name std (Cargo features says when each applies, and what a single-file consumer declares). These are the two lints that the emitter draws on the examples/cabin crate under cargo clippy: module_inception from the package and interface naming (veh.cabin and Cabin), and derivable_impls. The list is closed for that crate: the repository's just demo replaces allow with expect and runs clippy with -D warnings on the generated crate for examples/cabin, so a new lint, or a listed lint that no longer fires on it, fails that check. Single-file mode writes no lib.rs. A consumer that includes the generated file with include! puts #[allow(clippy::derivable_impls, clippy::module_inception)] on the mod that wraps the include!. Explicit crate-root links in the generated docs can be unresolved when the file is included inside another module (Documentation in the generated code).

Two things it may leave out, each with a note in the source it writes. A type whose size the compiler cannot bound — one that reaches itself, or a stream — carries no codec, and gets a __RIDL_FB_NO_CODEC_<NAME> constant whose documentation names the member and the reason. An interface the face cannot carry — a parameter with no declared type, a stream in either position, a query whose reply is a fallible T | E, or a contract clause outside the form the translator accepts — is skipped along with its descriptors, and gets a __RIDL_NO_FACE_<NAME> constant naming the interface and the reason, and, when an issue tracks the limit, that issue. An internal interface gets no face in any case (the design record gives the rule). When its descriptors are refused, its note says that the descriptors are absent and gives the reason. Neither is an error: the rest of the package is emitted, and the build succeeds.

The face names the ridl-rt port traits and nothing else: the crate carries no runtime and opens no socket, so an application supplies the ports. The one runtime in this workspace is ridl-loopback, which runs in process. examples/cabin/ is a worked example — a schema, and a consumer program against the crate built from it — and just demo generates that crate and runs the program, which prints one round trip per interaction kind through the async client and the command and the query again through the blocking one.

The manifest says which encodings a backend emits. There is no flag for the payload encoding. A [backend.<name>] table in the manifest holds an encodings list for the backend of that name, and ridl build sends each backend its own list:

[package]
name = "veh.cabin"
version = "1.0.0"

[backend.rust]
encodings = ["flatbuffers"]

The names are flatbuffers, proto3 and podbuf. An absent table, an absent key and an empty list all mean types only. The Rust backend builds each of the three, alone or together. A podbuf codec buffer starts on an 8-byte boundary, and the generated size tables hold Aligned buffers for it. The generated Cargo.toml enables one ridl-rt feature per named encoding, and none for types only. A single-file build has no manifest, so it is types only. Each emitted codec names its encoding, as ::ridl_rt::encoding::FlatBuffers or ::ridl_rt::encoding::Proto3; the face takes its encoding from its port type instead, so a consumer that binds a generated face to a runtime it did not write names an encoding only where it builds that runtime — over ridl-loopback, Loopback::new for FlatBuffers and Loopback::<E>::with_encoding for another. A program that writes its own port names the encoding in that port's Encoded implementation instead (Writing a port).

[backend.rust] wasm = true adds a module wasm to the generated crate, written to __ridl_wasm.rs. The module lists the payload types that have a FlatBuffers codec in WASM_PAYLOAD_TYPES, sorted by qualified name (veh.cabin.Temperature; an induced tuple by its Rust name), and the typl rule names in WASM_RULES, sorted. A type_id is an index into the list of the same build. When the target is wasm32 and the generated crate's feature wasm-exports is on, the module exports ridl_alloc, ridl_free, ridl_catalog_hash, ridl_verify and ridl_type_id, and no other function. ridl_type_id returns the type id of a payload type named by its qualified name, or -1 for a name the list does not hold. ridl_verify(type_id, ptr, len) returns 0 when the bytes verify as the type at index type_id, 1 for a malformed buffer, 2 plus the index of the broken rule in WASM_RULES, and -1 for an unknown type_id. A null ptr with a length, and a range past the end of memory, return 1. ridl_alloc returns 0 when the length is 0 or the allocation fails. The generated Cargo.toml declares the feature wasm-exports = ["std"] and no crate type, so a Rust consumer of the crate links no export. The wasm-exports feature gives the command that builds the module. The module writes the catalog hash of one unit: the root package's unit, or the one unit of the workspace's own packages when the manifest is a [workspace]. A build with no root package and other than one unit is refused. The option needs encodings to name flatbuffers, and the Rust backend refuses it otherwise. A package whose first segment is wasm refuses it too. A build with the option off removes a __ridl_wasm.rs that an earlier build wrote, and a build with it on refuses to overwrite a __ridl_wasm.rs that does not start with the generated marker. Single-file mode has no manifest, so it has no wasm module.

[backend.typescript] codec = true writes <base>.codec.ts beside the TypeScript module of every package that has a payload root with a codec (its own, or one of another package that its interfaces name), and turns the wasm module on when [backend.rust] writes no wasm key. A written wasm = false, and a manifest with no [backend.rust] table, are MANI-019. [backend.rust] encodings must still name flatbuffers, and the Rust backend refuses an implied wasm module otherwise.

[backend.rust] transcode = true asks the Rust backend for the transcoding functions between the encodings of the same table. The table must write at least two encodings elements; every written element counts, valid or not. Fewer than two written elements, or an absent encodings key, is MANI-020, reported on the transcode value. A written element that is unknown or repeated is also MANI-015. An encodings value that is not an array is MANI-015 only. The ridlc request carries a transcode option with the value true for that table, and no transcode option otherwise.

MANI-015 is an error when the encodings value is not an array of the known names or repeats a name, when wasm, codec or transcode is not a boolean, when a [limits] value is not an integer of 0 or more, or when [limits], [limits.kind] or [limits.interaction] is not a table, and MANI-016 is an error when the manifest of a workspace member holds a backend key or [backend.<name>] table: only the workspace root, or a standalone package, sets it. Any other key under [backend.<name>] is MANI-005. The table is not the backend. attribute namespace of an rsdl declaration. The lint RSDL-807 link-encoding-not-emitted warns when a link of the selected deployment carries an encoding that the emitted backend's list does not name. It is compared once per emitted backend that can carry a codec: the rust emit and each --plugin, and a backend named by both an --emit and a --plugin is compared once. A schema emit (proto, flatbuffers), the podbuf emit, the typescript emit and codegen-model are not compared, because their backends take no encodings option, and codegen-request is not compared either, because it writes its options into the request rather than emitting a codec from them. A [backend.<name>] table whose encodings list is empty declares that the backend emits no codec, and it is not compared either; a table written with no encodings key at all is the same declaration, as the manifest records the two forms alike. A backend with no table at all is compared, so a build that declared no encodings is still reported. An empty list is how a schema-only plugin silences the lint for its own backend, where the [lints] level silences it for every backend at once.

[limits] gives the interactions of a unit their payload limits, in bytes of encoded payload (ADR-0030 decision 12). A unit sets it in its own ridl.toml; the table of a workspace root does not apply to its members, and a package of a unit's subdirectory takes the unit's table.

[limits]
default = 4096                  # every kind with no entry below

[limits.kind]
signal = 256                    # signal, fixed, event, command or query
event = 2048

[limits.interaction]
"Climate.temperature" = 64      # Interface.member, quoted because of the dot

The table of a remote unit that [imports] names is read too, so its interactions record the owner's limits and the consumer computes the owner's catalog hash. The consumer reports no RIDL-151 or RIDL-152 for it.

The limit of an interaction is the first that is found of: its entry in [limits.interaction], the entry of its kind in [limits.kind], default, and the payload ceiling of 16,256 bytes. No limit is above the ceiling. A key of [limits.interaction] is the short name of the interface, or of the inline service (the last segment of its dotted name), then ., then the member; neither the package nor a dotted service name is part of it. When two interfaces or inline services of one unit share a short name, a key that uses the name is ambiguous.

An unknown kind in [limits.kind] is MANI-021, and a value above 16,256 is MANI-022. A key that names no interaction of the unit, or that is ambiguous, is RIDL-152, reported on the key. RIDL-151 is reported on an interaction whose payload has a largest encoded size, in an encoding that a [backend.<name>] table enables (FlatBuffers when no table names one), above the limit that an entry of [limits] gives it, or no finite bound. A command or query checks its request and its reply against its one limit, and a fixed is sized too. Both are errors, so they have no name and no level in [lints]. A payload above the ceiling under a declared limit draws RIDL-150 as well; where no entry gives a limit, only RIDL-150 applies. A package with an error that stops ridl build writing artifacts, or that depends on one, is not checked, and a unit with such a package reports no RIDL-152. An error in a manifest stops RIDL-150 in every package of the workspace, and RIDL-151 and RIDL-152 only in the packages beneath that manifest.

A [limits] entry that applies to an interaction is recorded in the IR, so adding, removing or editing one changes the catalog hash of the interaction's unit. An interaction that no entry reaches records no limit, and a unit with no [limits] table keeps its hash.

proto is a wire backend (ADR-0013 decision 2): it emits the typl surface — structs, enums, enum sets and unions, projected to proto3 messages and enums, with named-scalar constraints carried as comments — plus the interaction identity table, one enum per interface giving each signal, event, command, query and fixed its ordinal. It emits no service block, no call face, and no value store; store and dispatcher generation is not part of this emit (ADR-0018 decision 16).

flatbuffers is the second wire backend, with the same two tiers and the same ceiling. Its projection rules differ from proto3's where the targets differ — a union is isolated in a wrapper table, every struct is a table, a map is a vector of generated entry tables with no (key), and enum values are not prefixed because FlatBuffers scopes them inside their enum — and are recorded in ADR-0019.

podbuf is the third wire backend: it writes the C header, <base>.h, through which a C consumer reads a podbuf buffer that the gate has verified, with no library. The header holds the preamble and descriptor structs, one head struct per type with its pad members written out and _Static_assert checks on every sizeof and offsetof, the constants of the enums and the union tags, and inline accessor functions that read through the preamble's head size and answer 0 for a field past it. It refuses a big-endian target with #error. It takes no option. A package that lays out a struct, tuple or union of another package inline defines that head again behind a guard macro, so the headers of two packages can be included in one translation unit.

codegen-model is not a backend at all: it writes the lowered codegen model — one package, resolved over the scope the build read, with the scalar classes, the pinned name transforms, the resolved type references, the typl init and closure rules, the tombstones in their slots, the FlatBuffers projection and the interaction facts computed once — as canonical protobuf JSON, in the schema ridl.codegen.v1. It is the payload a codegen request carries (ADR-0020 decisions 8 and 9), the same JSON value as the request's model, so a plugin's fixture is a file ridlc wrote. The rust backend reads the model and nothing else. The other three backends above still read the IR, and a drift test in each of them asserts that what the backend derives and what the model states are the same fact.

codegen-request writes the whole request, to <base>.codegen-request.json: the same canonical protobuf JSON a plugin reads on its standard input, with schema, toolchain, model, options, artifactBase, generatedMarker, header and the deployment section. It is the artifact a plugin author debugs against — the request their plugin would receive for this package, written without running the plugin. Its model is the value codegen-model writes, so the two emits state one fact. Unlike codegen-model, it accepts the options of its own [backend.codegen-request] table and writes them into the request's options, because those options are part of what a plugin receives and an emit that refused them could never show a request carrying any.

--plugin runs a codegen plugin beside the emits — a backend that is an executable rather than part of ridl, over the contract generate(CodegenRequest) → CodegenResponse (ADR-0020 decisions 9 and 10; the as-built record is docs/design/codegen-plugins.md). The value is a language, or a language and a path:

• --plugin kotlin runs ridlc-gen-kotlin, found by walking PATH in order and taking the first directory that holds a file of that name (on Windows, ridlc-gen-kotlin.exe is also tried). No directory holding it is an error naming ridlc-gen-kotlin, and — like a compile error — a build that writes nothing.
• --plugin kotlin=/opt/gen/bin/kt-gen runs the executable at that path and skips the lookup. ridl still reports it as ridlc-gen-kotlin, with the path beside the name.

The flag repeats, once per plugin. Each plugin runs once per package the code emits are written for — ridl.std included, under the same rule as above — and receives on its standard input one ridl.codegen.v1.CodegenRequest in canonical protobuf JSON: schema ("ridl.codegen.v1") and toolchain (this ridl's version) first, then model (the same JSON value as the package's codegen-model artifact, one indentation level deeper), options (one encodings option when the root manifest's [backend.<language>] table names an encoding, as described above; empty otherwise; no flag sets one), artifactBase, the <base> of the emit list above, generatedMarker (the marker line) and header (the header text, an empty string when there is none), both always present, and deployment, the deployment section — the one --deployment names, or, with no flag, the one the source declares when it declares exactly one — absent when no deployment is carried. It answers on its standard output with one CodegenResponse: files, each a path relative to --out-dir with a text or binary content, and diagnostics, each a severity and a message. ridl writes the files; the plugin never touches the filesystem, so --out-dir means for a plugin exactly what it means for rust. A path that is absolute, has a .. or . or empty component, or contains \ is refused, and no file of that response is written. A diagnostic is reported prefixed with the plugin's name, at its severity; an error-severity one is a build that exits 1 with none of that response's files written, as an in-tree backend's failure is. A non-zero exit, a response that does not parse, a plugin that cannot be started, and a plugin still running after --plugin-timeout seconds (60 by default; the plugin is killed) are each one error naming the plugin, and the build exits 1. The plugin's standard error is passed through.

This repository builds two plugins for its test suite, and no release installs either: ridlc-gen-model is --emit codegen-model as a process, and ridlc-gen-rust is --emit rust as a process. A parity test runs each one through this path and compares its output with the in-process backend's, byte for byte. The TypeScript, proto3 and FlatBuffers backends run in process only. Writing a codegen plugin is the guide for a plugin author.

It writes one file per package per --emit target, under --out-dir (out by default), and — exactly like ridl check — ridl.lock at the workspace root when the manifest declares [imports], non-frozen. The exception is catalog, which writes one file per unit, named <unit>.catalog.binfb after the unit's manifest name, when any source package of the unit declares an interface or a service with an inline body, and no file for a unit that declares neither. <base> in the --emit list above is the package name when PATH is a package directory or a workspace root, and the input file's stem in single-file mode; the catalog of a single file is named after the file's package, which is its own unit.

When a package names a type from ridl.std, the standard package is written beside your own as one more file per --emit target — ridl.std.rs, ridl.std.ts, ridl.std.codegen.json — because generated code refers to standard types by package path and does not compile without it, and the model is lowered over the same scope. ridl.std.codec.ts joins them under [backend.typescript] codec = true only when a package's codec module imports it, for a payload type that is a ridl.std scalar. The three IR targets — ir-json, ir-text, ir-binary — get no such file: a direct IR dump records the packages the workspace declares, and ridl.std ships with the compiler rather than with the workspace (ADR-0007 decision 15). catalog gets no such file either: ridl.std declares no interface, so no ridl.std.catalog.binfb is written.

When the workspace declares a system (rsdl reference §3.1), each of the three IR targets also writes the lowered system — the closure, and every deployment with its placements, links, routes and surface set (rsdl reference §13) — as one more file named after the system's qualified name: veh.topology.Vehicle.system.json for system Vehicle in package veh.topology under --emit ir-json, .system.txtpb and .system.binpb for the other two.

Building a workspace of two packages that name no standard type, with no [imports]:

ridl build --out-dir out && find out -type f | sort

out/Cargo.toml
out/lib.rs
out/veh.cluster.rs
out/veh.common.rs

The Cargo.toml and the lib.rs are the crate root: the per-package files are flat, and the crate root is what gives them the module paths the generated code refers to each other by. Single-file mode writes neither, because one file is not a crate.

and a single .typl file with --emit rust,ir-json:

ridl build speed.typl --emit rust,ir-json --out-dir out && find out -type f | sort

out/speed.ir.json
out/speed.rs

Exit codes. 0 when the build compiles clean and every requested artifact is written. 1 when a diagnostic is an error — nothing is written for a package that fails to compile. An RSDL-7xx error is the one exception: it blocks only its own deployment (rsdl reference §13), so the build writes every artifact, leaves that deployment out of the lowered system, and still exits 1:

ridl build --out-dir out

error[TYPL-011]: unknown type name `Bogus`
  ┌─ ./demo.ridl:4:25
  │
4 │   signal currentSpeed : Bogus @10ms
  │                         ^^^^^

2 when the workspace itself cannot be found:

ridl build /nonexistent/ridl/workspace --out-dir out

error: `/nonexistent/ridl/workspace` does not exist

ridl test

ridl test --help

Run the property suite over a workspace: the range self-corpora and the contract-clause sampling (ridl §13). Exit 0 when every run passes, 1 on a self-corpus failure or an evaluation error, 2 on a compile error

Usage: ridl test [OPTIONS] [PATH]

Arguments:
  [PATH]  [default: .]

Options:
      --samples <SAMPLES>  Random parameter tuples drawn per `require` clause (minimum 1). Each clause also runs its parameters' boundary corpus, which is drawn first and is not counted here, so the total per clause is larger [default: 256]
      --format <FORMAT>    Output format for the report [default: text] [possible values: text, json]
  -h, --help               Print help

ridl test runs two checks per package: every constrained named type's boundary and violation corpus against the constraint validator (a self-consistency check of the toolchain, not of the model), and every require clause's satisfiability, sampled over each parameter's boundary values plus --samples random draws. ensure clauses are listed as observer stubs and never evaluated — there is no runtime to produce the result they need. The report goes to stdout; a compile error's diagnostics go to stderr instead, and no report prints at all.

It writes nothing, ever. The report is printed, never saved. ridl test runs the plain compile only — never the materialization step that makes ridl check write ridl.lock — so pointing the same [imports]-declaring workspace at ridl test produces no lockfile.

A clean run over an interface with two require clauses:

ridl test --samples 8

package cli.demo
  ranges
    Speed  ok — 4 boundary accepted, 2 violations rejected
  requires
    Cruise.setTargetSpeed.require[0]  ok — 3 boundary + 8 random of 12 satisfied  (speed > 0.0)
    Cruise.setTargetSpeed.require[1]  ok — 4 boundary + 8 random of 12 satisfied  (speed <= 250.0)
  ensures
    (none)
  summary — requires: 2 total, 2 evaluated; ensures: 0 listed

The same run with --format json prints one JSON object per package, on one line:

ridl test --samples 8 --format json

[{"contracts":[{"boundary_samples":4,"detail":null,"discarded_samples":0,"id":"Cruise.setTargetSpeed.require[0]","random_samples":8,"samples":12,"satisfied":11,"source":"speed > 0.0","status":"ok"},{"boundary_samples":4,"detail":null,"discarded_samples":0,"id":"Cruise.setTargetSpeed.require[1]","random_samples":8,"samples":12,"satisfied":12,"source":"speed <= 250.0","status":"ok"}],"package":"cli.demo","ranges":[{"boundary":4,"status":"ok","type":"Speed","violations":2}],"summary":{"ensures_listed":0,"nothing_evaluated":false,"requires_constant_false":0,"requires_errored":0,"requires_evaluated":2,"requires_skipped":0,"requires_suspect":0,"requires_total":2}}]

Exit codes. 0 above. 1 when a range self-corpus fails, or — the case a require clause reaches in practice — evaluating one raises an error, such as a division by zero every sampled input hits:

ridl test

package cli.demo
  ranges
    Divisor  ok — 4 boundary accepted, 2 violations rejected
  requires
    I.c.require[0]  ERROR — division by zero while evaluating `100 / (d - d) > 1`
  ensures
    (none)
  summary — requires: 1 total, 0 evaluated, 1 errored; ensures: 0 listed
  WARNING: no require clause was evaluated — this run tested no precondition (0 skipped of 1)

2 when the workspace fails to compile, when the workspace cannot be found, or when --samples 0 is given — sampling zero values is refused rather than silently clamped, because it would report every clause as unsatisfiable and call that a finding:

ridl test

error[TYPL-104]: range minimum 250 is greater than maximum 0
  ┌─ ./demo.ridl:2:20
  │
2 │ type Broken : km/h [250.0..0.0]
  │                    ^^^^^^^^^^^^

warning[TYPL-102]: `float` without both a range and a `step`
  ┌─ ./demo.ridl:2:15
  │
2 │ type Broken : km/h [250.0..0.0]
  │               ^^^^
  │
  = lint: `unbounded-float` (set its level in `[lints]` in ridl.toml)

ridl test --samples 0

error: `--samples` must be at least 1

Note the overloaded meaning: exit 1 here is a test failure (the toolchain found a problem worth failing the run over), not the breaking verdict ridl diff uses the same code for, and not the diagnostic error ridl check uses it for. A suspect finding — no sampled input satisfies a precondition — is reported in the same output but does not fail the run; only a self-corpus failure or an evaluation error does.

ridl fmt

ridl fmt --help

Reformat `.typl`, `.ridl` and `.rsdl` files in place (defaults to the current directory)

Usage: ridl fmt [OPTIONS] [PATH]

Arguments:
  [PATH]  [default: .]

Options:
      --check  Do not write; exit 1 if any file would change
  -h, --help   Print help

It writes every .typl/.ridl/.rsdl file under PATH back to itself in canonical form, unless --check is given or the file fails to parse. The walk skips vendor/ at every manifest root it meets, including one below a PATH that has no ridl.toml; ridl vendor fills that directory with copies of remote units that belong to their own owners. A PATH that is such a directory or lies under it is refused with exit 2. An .rsdl file takes the file layout (the header, one blank line between declarations). Systems, components, distributions, deployments and machines use canonical brace bodies, references and attributes. Deployments keep for before header attributes and nest machine blocks; source blank lines between machines remain. Interfaces and inline services use the canonical brace layout and member spacing. Named services keep commas between shapes, remove the optional trailing comma, and break overlong shape lists after the colon. Interaction timing precedes attribute blocks. Predicate attributes use block form; flag and assignment attributes stay inline when their code line fits.

Layout and line width. Formatted blocks use two spaces per indentation level. Parameter lists, tuple types and attribute value lists break into one item per line with commas between items when their code line exceeds the configured width. Overlong attribute blocks use one attribute per line; named service shape lists break after the colon. The default width is 100 characters. Width counts Unicode scalar values, including indentation. Trailing comments do not count towards the limit, and unbreakable code can exceed it. A comment embedded inside a single-line construct keeps that construct's source layout. Comments between interaction annotations stay with the preceding source annotation when timing moves first. If a moved annotation line comment would consume another trailing member comment, the whole member keeps its source layout.

A leading comment block is kept. A block of line comments before the package line, such as a copyright and licence notice, stays where it is, with or without a blank line between it and package. The formatter does not insert or remove that blank line.

EditorConfig example. Editors that support these properties can use this section in .editorconfig for the family's source files:

[*.{typl,ridl,rmdl,rsdl,rxdl}]
indent_style = space
indent_size = 2
max_line_length = 100

The CLI resolves max_line_length from .editorconfig for each file. The language server resolves it from the document path and formats the current buffer. An integer sets the width, off disables breaking, and absent, unset or invalid effective values use 100. Indentation remains two spaces; the formatter ignores indent_size, indent_style and client formatting options. Compiler profiles for .rmdl and .rxdl are still pending; the glob includes them for editor settings.

Exit codes. 0 when nothing needed rewriting, or the rewrite (without --check) succeeded. 1 under --check when a file would change, without writing it. Starting from speed.typl holding type Speed : km/h [0.0..250.0 step 0.5] on one line, with no blank line after the package declaration:

ridl fmt --check speed.typl; echo "exit: $?"

exit: 1

Reformatting it for real, then checking again:

ridl fmt speed.typl && cat speed.typl

package veh.common

type Speed: km/h [0.0..250.0 step 0.5]

ridl fmt inserted the blank line and tightened the colon; the shown text is cat's, since ridl fmt itself printed nothing. A second --check pass is now a fixed point:

ridl fmt --check speed.typl; echo "exit: $?"

exit: 0

and 1 — with or without --check — when a file has a parse error; the file is never rewritten, and the parse diagnostics render to stderr:

ridl fmt broken.typl

error[FORM-101]: expected `]`
  ┌─ broken.typl:2:22
  │
2 │ type X : integer [0..10ms]
  │                      ^^^^

error[TYPL-302]: duration literal in typl context
  ┌─ broken.typl:2:22
  │
2 │ type X : integer [0..10ms]
  │                      ^^^^

2 when an existing file cannot be read or written — a permissions error, for example:

ridl fmt unreadable.typl

error: cannot read unreadable.typl: Permission denied (os error 13)

A missing PATH, or a directory the walk cannot read, is the same exit 2 — naming the cause. This is a fix, recorded as ADR-0010 decision 6 and decision 1: before it, ridl fmt /nonexistent walked the missing path, found nothing, and reported success, and an unreadable directory reached partway through a larger walk was silently treated the same way — the one subcommand on this page that did not fail closed on a bad path. Both now report the directory read_dir failed on and the OS error:

ridl fmt /nonexistent/ridl/workspace

error: cannot read /nonexistent/ridl/workspace: No such file or directory (os error 2)

and, for a tree holding one ordinary file next to a subdirectory the walk cannot read into:

ridl fmt --check .

error: cannot read ./sub: Permission denied (os error 13)

Of the eight subcommands ADR-0010 decision 6 examined on 2026-07-27, it found ridl fmt is the only one that reliably names the actual unreadable path this way in every case it was tested against. ridl describe, added later, names the path in every exit-2 message about a path it was given. ridl check, ridl build, ridl baseline, ridlc check, and ridlc build still exit 2 on the same inputs, but with the wrong cause or none: an unreadable workspace root reports error: no `ridl.toml` found at or above `<path>` — confirmed directly against this build — and an unreadable subdirectory nested inside an otherwise-readable workspace reports a bare error: Permission denied (os error 13), naming no path at all — also confirmed directly. The other two subcommands decision 6 examined name a path only in part: ridl diff names the unreadable directory only when it is the argument given, and ridl test names the workspace root, not the subdirectory that failed. Tracked as issue driftsys/ridl#196, not fixed as of this page.

ridl diff

ridl diff --help

Compare two IR snapshots or source trees and classify the change: exit 0 compatible or identical, 1 breaking, 2 error

Usage: ridl diff [OPTIONS] [OLD] [NEW]

Arguments:
  [OLD]  The baseline: an `.ir.json` snapshot, a `.typl`/`.ridl` file, a package directory, or a workspace root
  [NEW]  The candidate, in the same forms as the baseline

Options:
      --format <FORMAT>      Output format for the report [default: text] [possible values: text, json]
      --explain <CATEGORY>   Print the classification rule for one change category and exit, instead of comparing snapshots. Takes a category exactly as the report prints it, e.g. `timing_changed`
      --encoding <ENCODING>  An encoding the change is judged for, as `[backend.<name>] encodings` names it; repeat the flag for several. A snapshot does not record the encodings a workspace builds. Only `podbuf` has a rule of its own: with it, a change under the heading "breaking under podbuf" is breaking; without it, compatible [possible values: flatbuffers, proto3, podbuf]
  -h, --help                 Print help

OLD and NEW each take one of three forms: an .ir.json snapshot, a directory of them (the shape .ridl/baseline/ takes), or source — a file, a package directory, or a workspace root — compiled in process. Only IR artifacts are recognised by name, and three inputs are refused rather than compiled (exit 2): an .ir.txtpb or .ir.binpb file, because diffs and baselines read .ir.json only (ADR-0014 decision 5); a directory that holds IR artifacts but no .ir.json snapshot and no source — no ridl.toml and no .typl/.ridl file — which is a snapshot directory in a refused encoding, not a source tree; and a directory with no source whose .ir.json snapshots sit one level below it, which is a path aimed one level too high. A directory is also exit 2, naming the entry, when an entry inside it named like a snapshot cannot be stat'ed — a symlink to a file that is gone — because skipping the entry would compare against a set one snapshot short; this is checked before the directory is read as a source tree, so a source directory holding such an entry is refused too. Every other input reaches the source compiler. Omit both and pass --explain <CATEGORY> instead to print that category's classification rule without comparing anything.

--encoding <ENCODING> names an encoding the change is judged for, with the names a manifest's [backend.<name>] encodings list takes (flatbuffers, proto3, podbuf); repeat the flag for several. A snapshot does not record the encodings a workspace builds, so the command does not read them from a manifest. Only podbuf has rules of its own, three of them. A struct field appended to a struct that another struct, a tuple or an exact-length array holds inline anywhere in the new side — in a struct, in the argument struct a call with several parameters induces, or in a tuple reply — is podbuf_inline_append, breaking with --encoding podbuf and compatible without it, because the inline copy cannot grow without moving the fields after it. An enum value, an enum-set flag or a union arm appended after which the podbuf integer of the enum, of the enum set or the tag of the union is a different integer, by width or by signedness — a value above 255, a flag at bit 8 or an arm past ordinal 255 widens a u8 to a u16, a value above 65535 or a flag at bit 16 a u16 to a u32, and a value above 4294967295 or a flag at bit 32 a u32 to a u64; an enum's integer is signed when a value is negative, and since a negative value appended to an enum that has values is an insert below its highest value, a breaking decl_added, the integer turns signed only when an enum with no value gains values — is podbuf_width_change, reported once per declaration with the old and the new integer, breaking with --encoding podbuf because every head that holds the enum, the enum set or the union lays out a different integer; an append that keeps the integer draws no such line. Without the flag the line is reported compatible, which holds under proto3; an enum-set flag that widens the integer also widens the enum set's FlatBuffers scalar, which ridl diff --encoding flatbuffers does not report yet (driftsys/ridl#1120). An enum value or an enum-set flag appended is podbuf_strict_enum_append, reported once per declaration with the appended names, breaking with --encoding podbuf and compatible without it, because every enum and enum set is strict and the verify of an older reader refuses a value or a bit its declaration does not name; an enum or an enum set whose append changes the integer draws only the podbuf_width_change line. The podbuf_inline_append line names each inline use, a struct field as <package>/<struct>/<field> and an interaction's request, reply or fixed payload as <package>/<interface>/<interaction>, and sits under the heading breaking under podbuf either way, so that a workspace that does not build podbuf still sees it. The search mirrors the heads the encoder lays out, a declaration and a named induced tuple: a struct that is a root of its own (a single named parameter, a named reply, a signal, event or fixed payload), that is used only behind a descriptor (the element of a bounded array, the key or value of a map entry, a union arm), or only inside an exact-length array that is itself a root (a fixed payload [S; 2..2], which has no head) draws no such line: the root or the descriptor's stride gives the producer's size. A tuple inside such a root is a head, and a struct inside that tuple is a use. A name outside the three is a usage error, exit 2. With Reading held inline by Bounds and a field appended to it:

ridl diff --encoding podbuf v1.typl v2.typl

breaking
  [compatible] decl_added veh.cluster/Reading/quality: (absent) -> quality
breaking under podbuf:
  [breaking] podbuf_inline_append veh.cluster/Reading/quality: (absent) -> nested inline in veh.cluster/Bounds/range

It writes nothing. The report goes to stdout; a compile error's diagnostics go to stderr instead and no report prints.

Two identical sources:

ridl diff old.ridl old.ridl

identical

An appended interaction — compatible:

ridl diff old.ridl compatible.ridl

compatible
  [compatible] interaction_appended veh.cluster/VehicleStatus/doorClosed: (absent) -> event doorClosed

A signal's payload type changed — breaking:

ridl diff old.ridl breaking.ridl

breaking
  [compatible] decl_added veh.cluster/Speed2: (absent) -> type
  [breaking] payload_changed veh.cluster/VehicleStatus/currentSpeed: Speed -> Speed2

A named-form service's list is a set of interfaces: an interface joining it is service_interface_added, one leaving it service_interface_removed, a reorder no change, and both are compatible, because an interface's number comes from its unit's interfaces.lock and the routing key does not contain the service. A removal is still visible in source — the service.member addresses of that interface stop resolving under the service — so the text report lists it under a heading, shared with interface_renamed, printed once as a line ending in a colon, after every change that has no heading. The JSON report carries the category word and no heading field. With interface K added and J dropped from service veh.cluster.dash : I, J:

ridl diff dash-old.ridl dash-new.ridl

compatible
  [compatible] decl_added veh.cluster/K: (absent) -> interface
compatible on the wire, visible in source:
  [compatible] service_interface_removed veh.cluster/veh.cluster.dash/J: J -> (removed)

An interface is matched by its number from the unit's interfaces.lock, within the unit, not by its name — a declared interface and a service's inline shape alike. A rename that keeps its number, recorded with ridl lock <unit dir> --rename Old=New, is interface_renamed: compatible on the wire, because the number is the routing identity, and visible in source, because the generated identity-table names change, so it shares the heading above; the path carries the new name, and a change inside the renamed interface is reported under the new name too. A number gone from the new side is interface_retired when that side's lock retires it, and decl_removed, breaking, otherwise. Against an old side whose numbers are frozen, a declaration with no lock entry carries a provisional number, which is no identity: it is decl_added, and it is never matched to an old interface, so a rename the lock does not record is decl_removed plus decl_added. Against a provisional old side, interfaces are matched by name, as described below. Two sides with no lock file — two bare source trees, or a snapshot published before the lock existed — are matched by name. Interfaces are matched within the unit, and the names on both sides of a change are catalog names, so an interface moved between two sibling packages of one unit keeps its number and is reported as interface_renamed, from the old catalog name to the new one. With J renamed to Jay on its number, the lock beside each file recording it, and Jay no longer listed in service veh.cluster.dash : I, J:

ridl diff old/dash.ridl new/dash.ridl

compatible
compatible on the wire, visible in source:
  [compatible] interface_renamed veh.cluster/Jay: J -> Jay
  [compatible] service_interface_removed veh.cluster/veh.cluster.dash/J: J -> (removed)

An interface matched by name across a provisional old side has its number and its provisional flag compared, because the catalog hash covers both. When the number is the same on both sides and only the new side is frozen — the number ridl lock froze in place — the change is interface_frozen: compatible, because the routing key did not move, and listed under the heading "compatible on the wire, may change the catalog hash", which it shares with enum_reordered, because the catalog hash changes and a generated face refuses a port whose catalog hash is another one. With old a unit before ridl lock and new the same unit after it:

ridl diff old new

compatible
compatible on the wire, may change the catalog hash:
  [compatible] interface_frozen veh.cluster/Doors: 1 (provisional) -> 1

A number that differs between the two sides is interface_number_changed, breaking, because the number is the routing key. Between two builds with no lock, an interface added before Doors in byte order of the name moves its provisional number:

ridl diff old new

breaking
  [breaking] interface_number_changed veh.cluster/Doors: 1 (provisional) -> 2 (provisional)
  [compatible] decl_added veh.cluster/Aux: (absent) -> interface

A number 0 on either side, from a snapshot written before the lock existed, is not compared. A published baseline never holds a provisional number, because ridl baseline refuses one (RIDL-411), so both categories are seen between two builds, or in a reversed comparison whose old side is a build.

An enum value or an enum-set bit takes its identity from the explicit number it declares, so a body whose difference is only order — its values or bits reordered with no number changed, an enum's reserved list reordered with no entry changed, or both — moves nothing on the wire. The change is enum_reordered, compatible, on the container's path and under the same heading. The catalog hash covers only the declarations an interface reaches: when an interface reaches the enum or enum set, the order of its values or bits, and of an enum's reserved list, is part of the hash, so the hash changes then. With the values of enum GearPosition reordered:

ridl diff old.ridl new.ridl

compatible
compatible on the wire, may change the catalog hash:
  [compatible] enum_reordered veh.cluster/GearPosition

A value or bit whose number changed is member_reordered, breaking, with the old and the new number in the detail.

The breaking comparison above with --format json:

ridl diff old.ridl breaking.ridl --format json

{
  "verdict": "breaking",
  "changes": [
    {
      "path": "veh.cluster/Speed2",
      "category": "decl_added",
      "verdict": "compatible",
      "before": null,
      "after": "type"
    },
    {
      "path": "veh.cluster/VehicleStatus/currentSpeed",
      "category": "payload_changed",
      "verdict": "breaking",
      "before": "Speed",
      "after": "Speed2"
    }
  ]
}

At the system. When both sides are source whose workspace declares a system, ridl diff also lists the changes to the lowered system that are not contract changes, under two headings and with no verdict (rsdl reference §14): placement changed for a deployment or a machine added or removed, a machine made external, or an instance moved to another machine; composition changed for a component added to or removed from the system, an offers or requires line added or removed, instances changed, a component made external, a distribution added or removed, or a member line added to or removed from a distribution. The verdict and the exit code are the contracts' alone.

Moving Panel from machine Front to machine Rear in deployment Desk:

ridl diff old new

identical
placement changed
  Desk/Rear: (absent) -> machine
  Desk/Front: machine -> (removed)
  Desk/veh.demo.Panel.Unit: Front -> Rear

With --format json the headings are the keys placement_changed and composition_changed, each a list of {"path", "before", "after"}, present only when they hold a change. An .ir.json snapshot, or a directory of them, carries no system — ridl baseline publishes package snapshots only — so a diff against .ridl/baseline/ lists no system change.

--explain for one category:

ridl diff --explain payload_changed

payload_changed
A signal, event, or fixed payload type changed.
  breaking    any direction, a stream added or removed included

Exit codes. 0 for identical and compatible above. 1 for breaking above — the verdict, not a tool failure. 2 when a side fails to compile:

ridl diff old.ridl broken.ridl

error[TYPL-011]: unknown type name `NoSuchType`
  ┌─ broken.ridl:4:25
  │
4 │   signal currentSpeed : NoSuchType @10ms
  │                         ^^^^^^^^^^

2 when an input path does not exist:

ridl diff old.ridl does-not-exist.ridl

error: does-not-exist.ridl: `does-not-exist.ridl` does not exist

2 when neither both inputs nor --explain are given:

ridl diff old.ridl

error: `ridl diff` needs both an old and a new input, or `--explain <CATEGORY>`

and 2 for an --explain category that is not one of the categories the tool knows, which the error lists in full:

ridl diff --explain not_a_real_category

error: unknown change category `not_a_real_category`
the categories `ridl diff` reports are:
  decl_added
  decl_removed
  interface_renamed
  interface_retired
  interface_frozen
  interface_number_changed
  member_reordered
  enum_reordered
  interaction_appended
  interaction_inserted
  interaction_reordered
  interaction_removed
  interaction_retired
  kind_changed
  payload_changed
  return_changed
  params_changed
  timing_changed
  rpc_bound_changed
  limit_changed
  contract_changed
  interaction_class_changed
  width_changed
  constraint_changed
  init_changed
  reserved_name_redeclared
  service_changed
  service_interface_added
  service_interface_removed
  doc_only
  visibility_changed
  podbuf_inline_append
  podbuf_width_change
  podbuf_strict_enum_append

ridl lock

ridl lock --help

Allocate a number to every interface that has none and write each unit's `interfaces.lock`; with `--rename` or `--retire`, rewrite one unit's entries in place instead. Exit 0 when the file is written or nothing changes, 1 on a diagnostic error, 2 on a bad flag or a path or I/O failure. `ridl lock merge` is the git merge driver for the file

Usage: ridl lock [OPTIONS] [PATH]
       ridl lock <COMMAND>

Commands:
  merge  The git merge driver for `interfaces.lock`: a three-way merge over entries matched by number, written to OURS. Exit 0 when the merge is clean, 1 when entries disagree (they are left between conflict markers of MARKER_SIZE, and the file is RIDL-410 until resolved), 2 when an input cannot be read or does not parse (OURS is left as it was). Register it with `.gitattributes` and `git config` as the CLI reference documents
  help   Print this message or the help of the given subcommand(s)

Arguments:
  [PATH]  A unit directory, a workspace root, or a file. A directory named `merge` is spelled `./merge`, since the bare word is the subcommand [default: .]

Options:
      --rename <OLD=NEW>  Rewrite the live entry OLD to hold the key NEW, keeping its number (repeatable). NEW must be a declaration without an entry
      --retire <NAME>     Mark the live entry NAME retired, keeping its line and its number (repeatable). NAME must no longer be declared
  -h, --help              Print help

It writes one interfaces.lock per unit, in the directory of the unit's ridl.toml — the line table that gives every interface of the unit its number (ridl §11): a # header, next N, then one entry per interface, Name N, with the word retired after the number when the interface is gone. An interface of a subpackage is keyed by its name relative to the unit, such as cluster.Speed. A service's inline shape is an interface too and is keyed service: followed by the service's full dotted name. Only ridl lock writes the file: the compiler reads it beside the sources, and ridl fmt never touches it.

Plain ridl lock is the only form that allocates. Every declared interface whose name has no live entry gets the next free number, in byte order of the name, and the file is written; a declaration that already has its entry is left as it is. Over a unit holding interface Zone and interface Cabin and no lock file yet:

ridl lock . ; echo "exit: $?"

allocated Cabin 1
allocated Zone 2
exit: 0

# interfaces.lock — written by ridl lock; do not edit by hand.
next 3
Cabin 1
Zone 2

Run again with nothing to allocate, it prints nothing, writes nothing and exits 0. Over a workspace it writes each unit's own file, and each output line is prefixed with the unit directory relative to PATH and a colon: hvac: allocated Cabin 1. A PATH inside a workspace member compiles the whole workspace and allocates in, edits and reports on that member only. Until ridl lock has run, a declaration with no entry compiles with a provisional number, which carries no identity. The catalog hash covers each number and its provisional flag, so ridl lock changes it: ridl diff reports a number frozen in place as interface_frozen, compatible, and a number frozen as another one as interface_number_changed, breaking.

The reverse case — a live entry whose interface is gone from the source — is RIDL-409 from the compiler, and plain ridl lock refuses to allocate over it: nothing is written, exit 1. The two flags are that diagnostic's fix, and they run with RIDL-409 present:

• --rename OLD=NEW rewrites the entry OLD to hold the key NEW in place, keeping its number, when NEW is a declaration without an entry — the same interface under a new name. Printed as renamed Old New N.
• --retire NAME marks the entry retired, keeping its line and its number, when nothing declares NAME any more. Printed as retired Name N.

Both are repeatable, neither allocates, and PATH must resolve to exactly one unit. OLD, NEW and NAME are dotted names relative to the unit, such as cluster.Old, so a rename across sibling packages is ridl lock <unit dir> --rename cluster.Old=cluster.New. An interfaces.lock in a subdirectory of a unit is not read and draws the warning RIDL-416 (lock-in-subdirectory). A rename keeps the number because the number, not the name, is the interface's wire identity; the old name is then free for a later, unrelated interface. Starting from the file above with interface Zone renamed to interface Lane in the source:

ridl check . ; echo "exit: $?"

error[RIDL-409]: `Zone` is a live entry of `interfaces.lock` with no declaration in the unit: run `ridl lock . --rename Zone=New` when a declaration without an entry, `New`, is this interface under a new name, or `ridl lock . --retire Zone` when the interface is gone
  ┌─ ./interfaces.lock:4:1
  │
4 │ Zone 2
  │ ^^^^^^

exit: 1

ridl lock . --rename Zone=Lane ; echo "exit: $?"

renamed Zone Lane 2
exit: 0

The merge driver. Two branches that each edited interfaces.lock merge through ridl lock merge, a three-way merge over entries matched by number rather than over lines. git runs it when the repository registers it: one versioned line in .gitattributes, and one git config line per clone, which git does not version.

interfaces.lock merge=ridl-lock

git config merge.ridl-lock.driver "ridl lock merge %O %A %B %L"

ridl lock merge --help

The git merge driver for `interfaces.lock`: a three-way merge over entries matched by number, written to OURS. Exit 0 when the merge is clean, 1 when entries disagree (they are left between conflict markers of MARKER_SIZE, and the file is RIDL-410 until resolved), 2 when an input cannot be read or does not parse (OURS is left as it was). Register it with `.gitattributes` and `git config` as the CLI reference documents

Usage: ridl lock merge <BASE> <OURS> <THEIRS> <MARKER_SIZE>

Arguments:
  <BASE>         The common ancestor's file (`%O`); an empty file reads as `next 1`
  <OURS>         The current branch's file (`%A`); the result is written here
  <THEIRS>       The other branch's file (`%B`)
  <MARKER_SIZE>  The length of a conflict marker line (`%L`, 7 by default)

Options:
  -h, --help  Print help

At each number the driver applies git's own three-way rule: a change on one side is taken, the same change on both sides is kept once, and two different changes to one entry — a retire against a rename, or two renames — are left between conflict markers, with every other entry written plain. One rule is the driver's own: when both sides allocated one number to two different interfaces, ours keeps the number and theirs is renumbered to the next free one, which is safe because a branch never allocates. A live name on two numbers — each side allocated the same interface on its own number — is a conflict too. next is the maximum of the three sides plus one per renumbered entry, so it is never lowered. With A 1, B 2 as the base, ours retiring B and theirs renaming it to Bee:

# interfaces.lock — written by ridl lock; do not edit by hand.
next 3
A 1
<<<<<<< ours
B 2 retired
=======
Bee 2
>>>>>>> theirs

The file is malformed (RIDL-410) until an author keeps one side and deletes the markers, and ridl check refuses it until then. git's union driver is not a substitute: it discards the base, and resurrects a renamed or retired entry silently. An empty BASE — what git passes when both branches created the file — reads as next 1 with no entries. A package directory named merge is spelled ./merge: the bare word is the subcommand.

Exit codes. 0 when the file is written or there is nothing to change. 1 on a diagnostic error over the source, with nothing written: a live entry with no declaration when plain ridl lock is asked to allocate (RIDL-409), a malformed lock file — a git conflict left in it included — (RIDL-410), or any other compile error, in any package of the workspace. 2 when the path is missing or unreadable, on a bad flag — --rename naming no live entry or a NEW that is not a declaration without an entry, --retire naming an interface that is still declared, either flag over more than one package — or on an I/O failure writing the file. Every cell is confirmed against the built binary by crates/ridl/tests/lock_cli.rs. ridl lock merge exits 0 when the three sides merge clean and OURS is written; 1 when entries disagree — OURS is written with the conflict markers and is malformed until resolved; 2 when an input cannot be read or does not parse (OURS is left as it was), when MARKER_SIZE is not a number from 1 up, or on an I/O failure writing OURS. Every cell is confirmed by crates/ridl/tests/lock_merge.rs, which also registers the driver in a temporary repository and merges two branches through git.

ridl lsp

ridl lsp --help

Run the language server over stdio: exit 0 after `shutdown` then `exit`, 1 when the client ends the session without `shutdown`, 2 on a transport error. Editors spawn this. Stdio is the only transport

Usage: ridl lsp [OPTIONS]

Options:
      --stdio                  Select the stdio transport. Accepted because editor clients pass it, as the LSP specification recommends; omitting it changes nothing
      --clientProcessId <PID>  The editor's process id, which the LSP specification recommends a server accept. Ignored: the `initialize` request carries it too
  -h, --help                   Print help

ridl lsp hosts the language server: behavior lives in crates/ridl-lsp, and this subcommand only wires the stdio transport. An editor spawns it and speaks the Language Server Protocol over its stdin and stdout.

The server never fetches. It reads the remote units of [imports] from vendor/ at the manifest root and then from the cache, as ridl check --frozen does, so run ridl check or ridl vendor once in a fresh clone. It loads the remote units once, when it loads the workspace, and does not reload them when ridl.lock changes: after a ridl check that fetches a unit or rewrites ridl.lock, restart the server. It publishes no diagnostics for a file of a remote unit; it shows the errors of a remote unit once per load, in one window message.

Flags. --stdio and --clientProcessId=<PID> are accepted and change nothing. The LSP specification (3.17, "Implementation Considerations") recommends that a server accept both, and editor clients pass them: the VS Code client runs the server as ridl lsp --stdio. Stdio is the only transport, so --pipe and --socket are refused with exit 2. The client's process id also arrives in the initialize request.

Exit codes. They follow the LSP specification (3.17, "Exit Notification"). 0 on a clean shutdown — the client sends shutdown then exit. 1 when the client sends exit with no shutdown before it, or closes stdin after the handshake with no shutdown. 2 when the transport ends before the initialize handshake, or fails for any other reason. All four outcomes are confirmed directly against the built binary by crates/ridl/tests/servers.rs.

ridl mcp

ridl mcp --help

Run the MCP server over stdio for an agent host: exit 0 on a clean shutdown, 2 on a transport error. It takes no flag of its own

Usage: ridl mcp

Options:
  -h, --help  Print help

ridl mcp serves the Model Context Protocol over stdio with nine tools:

• ridl_check checks workspace files or a source text.
• ridl_explain explains a diagnostic code or diff category.
• ridl_resolve resolves a declaration and its location.
• ridl_describe_type describes a non-interface declaration.
• ridl_list_interactions lists an interface's interactions.
• ridl_references lists declarations and interactions using a declaration.
• ridl_dependencies lists package dependencies and dependents.
• ridl_metrics reports package coupling and interface cohesion groups.
• ridl_diff compares source workspaces or IR snapshots.

Behavior lives in crates/ridl-mcp; this subcommand builds the Tokio runtime and wires the stdio transport. An agent host spawns it and speaks MCP over stdin and stdout. The crate README documents input and output schemas, tool errors and the read-only workspace contract. The command takes no flag of its own.

Exit codes. 0 on a clean shutdown: the host closes the server's stdin, which is how a stdio host ends an MCP session. 2 when the Tokio runtime fails to build, when the transport ends before the initialize handshake, or when a task the SDK runs for the session fails after it. A read failure on stdin after the handshake is not distinguishable from the host closing stdin — the SDK logs it and ends the session the same way — so it exits 0. There is no exit 1: ridl mcp answers no question that can come back negative. The clean shutdown and the transport ending before the handshake are confirmed directly against the built binary by crates/ridl/tests/servers.rs; a session-task failure cannot be provoked through the server, so its mapping is tested on its own in crates/ridl-mcp.

ridl init

ridl init --help

Scaffold a new unit in a directory that exists (defaults to the current directory): a package, or with `--workspace` a workspace and one member. Writes `ridl.toml` and one source file, and exits 2 without writing anything when a target file exists, the name is not a legal package name or holds a reserved word, or a `ridl.toml` above or below the directory would make a manifest inside a unit (MANI-013)

Usage: ridl init [OPTIONS] [PATH]

Arguments:
  [PATH]  The existing directory to scaffold into [default: .]

Options:
      --workspace    Scaffold a workspace root and one member instead of a package
      --name <NAME>  The package name (the member name with `--workspace`); the directory name by default
  -h, --help         Print help

Writes the files of a new unit into a directory that already exists, and nothing else. The default is one standalone package: a ridl.toml that holds a [package] table with the version 0.1.0, and <name>.ridl in the same directory, which declares package <name>, one unit-carrying type and one interface with one signal. ridl check and ridl fmt --check draw nothing on it. On success the command prints Created package <name> to stdout.

--workspace writes a root ridl.toml with [workspace] members = ["<name>"], and the package above in the directory <name> under it. The command then prints Created workspace <name>, and ridl check passes from the root and from inside the member.

The name is the directory's basename when that is already a legal package name (lowercase dot-separated segments, each a letter followed by letters or digits). The basename is taken from the path as written, so a symbolic link is not followed to find it. The command never rewrites a name: a basename that is not legal exits 2 with an error that asks for --name, and so does a --name value that is not legal. A name with a reserved word as a segment, such as type or veh.signal, is also refused, because a source file that declares it does not parse. With --workspace, --name names the member and the root directory keeps its own name.

Exit codes. 0 when the files are written. 2, with an error: line on stderr and nothing written, when a target file already exists, the path is not a directory, the name is not legal or holds a reserved word, or a ridl.toml above or below the package directory would make a manifest inside a unit (MANI-013): the directory sits inside another unit or inside a workspace, or it already holds a ridl.toml in a subdirectory that ridl check would also reject. The search below is the loader's own: it skips directories whose name starts with a dot and does not follow symbolic links. This command does not add a member to an existing workspace. The search upward does not stop at a .git directory, because MANI-013 does not, and it follows symbolic links. Every target is checked before any file is written, the member files are written before the workspace root manifest, and a write that fails removes the paths this command created. There is no exit 1. The cases are confirmed against the built binary by crates/ridl/tests/scaffold_cli.rs.

ridl new

ridl new --help

Create a directory, with its parents, and scaffold a new unit in it, as `ridl init` does. Exits 2 without writing anything when the path exists

Usage: ridl new [OPTIONS] <PATH>

Arguments:
  <PATH>  The directory to create; it must not exist

Options:
      --workspace    Scaffold a workspace root and one member instead of a package
      --name <NAME>  The package name (the member name with `--workspace`); the directory name by default
  -h, --help         Print help

Creates the directory at PATH, with its parents, and scaffolds into it exactly as ridl init does, with the same flags, the same output and the same refusals. A PATH that already exists exits 2 and leaves the file system as it was. The name defaults to the last component of PATH.

ridl new vehicle-demo --name demo

ridl describe

ridl describe --help

Print a catalog descriptor as strict JSON, after verifying it

Usage: ridl describe <PATH>

Arguments:
  <PATH>  The `<unit>.catalog.binfb` file `ridl build --emit catalog` wrote

Options:
  -h, --help  Print help

Prints a catalog descriptor written by ridl build --emit catalog as JSON after verifying it; a file that is not a descriptor, or is malformed, is rejected as a whole with exit code 2.

The transcript below is abridged: it is the output for the test corpus in crates/ridl/tests/baseline-corpus, with each ... line standing for lines that were removed. The keys print in alphabetical order. First comes compatible, the earlier catalog hashes the descriptor lists as compatible with this one, each as its 32 bytes; it is empty here, because the corpus's published baseline holds no corpus.baseline.catalogs file. Then come the 32 bytes of the catalog hash, one entry per interface, the unit name, the retired numbers, the toolchain version that wrote the file, and the descriptor's schema version.

ridl build crates/ridl/tests/baseline-corpus --emit catalog
ridl describe out/corpus.baseline.catalog.binfb

{
  "compatible": [],
  "hash": [
    105,
    123,
    139,
    ...
  ],
  "interfaces": [
    {
      "members": [
        {
          "kind": "Signal",
          "limit": null,
          "name": "currentSpeed",
          "ordinal": 1,
          "payloads": [
            {
              "max_sizes": [
                {
                  "bytes": 46,
                  "cause": "Unspecified",
                  "encoding": "FlatBuffers",
                  "state": "Bounded"
                }
              ],
              "role": "value",
              "type_name": "Speed"
            }
          ],
          "timing": {
            "max_us": "10000",
            "min_us": "10000",
            "mode": "StrictPeriodic"
          }
        },
        ...
      ],
      "name": "VehicleStatus",
      "number": 1,
      "provisional": true,
      "reserved_ordinals": []
    },
    ...
  ],
  "name": "corpus.baseline",
  "retired": [],
  ...
  "version": 1
}

Exit codes. 0 when the descriptor was printed. 2 for a missing or unreadable path, a file that is not a catalog descriptor, a version this toolchain does not read, a malformed buffer, or an I/O failure writing to stdout (a pipe whose reader has gone); the message names the path and the cause. There is no exit 1: ridl describe answers no question that can come back negative. The exit-0 outcome, the missing path, the foreign file, a malformed buffer (three fixtures), a version the toolchain does not read, and the write failure on stdout are confirmed against the built binary by crates/ridl/tests/describe_cli.rs.

ridl vendor

ridl vendor --help

Copy every remote unit of the workspace's `[imports]` into `vendor/` at the manifest root, so a `--frozen` build needs no network and no cache. Every directory in `vendor/` that no `[imports]` key names is removed; files and hidden entries are left. Exit 0 when `vendor/` was written or there was nothing to change, 1 on a diagnostic error (`vendor/` is left untouched; `ridl.lock` may be updated), 2 on a missing or unreadable path, a fetch failure, or an I/O failure. With `--check`, compare `vendor/` with the imports and `ridl.lock` instead, writing nothing

Usage: ridl vendor [OPTIONS] [PATH]

Arguments:
  [PATH]  A unit directory, a workspace root, or a file; the manifest root above it is the one vendored [default: .]

Options:
      --check  Compare `vendor/` with `[imports]` and `ridl.lock` instead of writing: no network, no write. Exit 0 when `vendor/` matches, 1 on drift or another diagnostic error, 2 on a missing or unreadable path
  -h, --help   Print help

ridl vendor makes a project build with no network and no cache; the Remote units and ridl vendor chapter is the guide. PATH is a unit directory, a workspace root or a file, and defaults to the current directory; the command acts on the manifest root above it, found as ridl check finds it, so vendor/ is at the workspace root whichever member the command runs from. It then does three things:

1. It takes the union of the [imports] of the root manifest and of every member.
2. It materializes each unit as ridl check does, from the cache or by a fetch, and rewrites ridl.lock. It reads the cache and never vendor/, so a URL that changed is fetched and its directory replaced.
3. It brings vendor/ to exactly that set. Each unit is written whole into a staging directory and renamed into place under its [imports] key, with the bytes of its files unchanged. Every directory directly under vendor/ whose name is no [imports] key is removed, whether or not ridl vendor wrote it, so that, after a run, no directory other than a remote unit's remains among the non-hidden entries of vendor/; a file, a symbolic link and a hidden entry (a name that starts with .) are left alone. Nothing in vendor/ changes when the run has an error.

Each changed unit prints one line, vendored <key> or removed <key>; a run that changes nothing prints vendor/ is up to date; nothing to change. A unit's own vendor/ directory is copied with the unit, because it is part of the tree hash, and is skipped when the unit is read.

The tree hash is computed over the bytes of each file, so a checkout that converts line endings changes the bytes of a vendored file and makes its unit MANI-107. Mark the directory -text in .gitattributes with the line vendor/** -text, which stops line-ending conversion.

ridl vendor

After that, ridl check --frozen reads vendor/<key>/ first, only when ridl.lock pins a tree for the unit. For any other unit it reads the cache first, which gives the pin, and a vendored directory, if present, is then verified against that pin and read in place of the cache entry. A vendored tree that no longer matches its tree hash is MANI-107 and names ridl vendor.

ridl vendor exit codes.

ridl vendor applies no [lints] levels, and a lint that is allow by default is left out of its output, as for ridl lock.

ridl vendor --check compares vendor/ with the imports and ridl.lock. It fetches nothing, reads no cache and writes nothing, so it is the check to run in CI. It reports one diagnostic per unit:

• MANI-109, an imported unit with no directory in vendor/;
• MANI-110, a directory in vendor/ that no [imports] key names;
• MANI-107, a vendored tree that does not match its tree hash;
• MANI-103 or MANI-108, a unit that ridl.lock does not pin or pins with no tree, because its directory cannot be verified.

A manifest that does not parse is reported too, so a broken manifest is never a clean vendor/.

ridl vendor --check exit codes.

ridlc

ridlc --help

The RIDL family compiler (plumbing)

Usage: ridlc <COMMAND>

Commands:
  check  Type-check a file, package directory, or workspace
  build  Compile to the selected artifacts
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

ridlc has no humane defaults: PATH is required on both subcommands, and build's --out-dir is required rather than defaulted to out. Both are usage errors — exit 2 — courtesy of clap, not application code:

ridlc check

error: the following required arguments were not provided:
  <PATH>

Usage: ridlc check <PATH>

For more information, try '--help'.

ridlc check

ridlc check --help

Type-check a file, package directory, or workspace

Usage: ridlc check [OPTIONS] <PATH>

Arguments:
  <PATH>  The `.typl` file, package directory, or workspace root

Options:
      --frozen  Verify remote imports against `ridl.lock` without fetching or regenerating it (CI mode, ADR-0002 §7)
  -h, --help    Print help

It writes ridl.lock under the same condition ridl check does — the manifest declares [imports], the run is non-frozen, and materialization found no error — because ridl check calls this very function (ridlc::run_check) directly, forwarding its own PATH and --frozen. Otherwise it reads the workspace, renders diagnostics to stderr, and touches no file.

Exit codes. 0 clean, 1 a diagnostic is an error, 2 an input/output or usage error — identical in shape to ridl check, and, on the same input, identical in rendered text:

ridlc check .

error[TYPL-104]: range minimum 250 is greater than maximum 0
  ┌─ ./demo.ridl:3:19
  │
3 │ type Speed : km/h [250.0..0.0 step 0.5]
  │                   ^^^^^^^^^^^^^^^^^^^^^

run over the same directory as the type Speed : km/h [250.0..0.0 step 0.5] example under ridl check above — byte for byte the same diagnostic, confirmed by diffing the two runs' stderr. A workspace ridlc cannot find is the same exit 2 as ridl check:

ridlc check /nonexistent/ridl/workspace

error: `/nonexistent/ridl/workspace` does not exist

ridlc build

ridlc build --help

Compile to the selected artifacts

Usage: ridlc build [OPTIONS] --out-dir <OUT_DIR> <PATH>

Arguments:
  <PATH>
          The `.typl` file, package directory, or workspace root

Options:
      --out-dir <OUT_DIR>
          The directory to write generated artifacts into

      --emit <EMIT>
          The artifacts to emit: `rust` (default), `ir-json`, `ir-text`, `ir-binary`, `typescript`, `proto`, `flatbuffers`, `podbuf`, `codegen-model`, `codegen-request`, `catalog`

          Possible values:
          - rust:            Idiomatic Rust source, written to `<base>.rs`
          - ir-json:         The lowered IR v2 as exact-decimal JSON, written to `<base>.ir.json`, and the lowered system to `<pkg.Name>.system.json`
          - ir-text:         The lowered IR v2 as prototext, written to `<base>.ir.txtpb`, and the lowered system to `<pkg.Name>.system.txtpb`
          - ir-binary:       The lowered IR v2 as protobuf binary, written to `<base>.ir.binpb`, and the lowered system to `<pkg.Name>.system.binpb`
          - typescript:      Idiomatic TypeScript source, written to `<base>.ts`, and the codec module `<base>.codec.ts` with `[backend.typescript] codec = true`
          - proto:           The proto3 schema, written to `<base>.proto`
          - flatbuffers:     The FlatBuffers schema, written to `<base>.fbs`
          - podbuf:          The podbuf C header, written to `<base>.h`
          - codegen-model:   The lowered codegen model (`ridl.codegen.v1`) as canonical protobuf JSON, written to `<base>.codegen.json`
          - codegen-request: The whole codegen request a build hands a backend, as canonical protobuf JSON, written to `<base>.codegen-request.json`
          - catalog:         The catalog descriptor an engine reads, written to `<unit>.catalog.binfb` for every unit that declares an interface or a service with an inline body: a FlatBuffers file of the unit's interfaces, their members and their catalog hash
          
          [default: rust]

      --plugin <LANGUAGE[=PATH]>
          A codegen plugin to run beside the emits, once per package: `<LANGUAGE>` runs `ridlc-gen-<LANGUAGE>` from PATH, `<LANGUAGE>=<PATH>` runs the executable at PATH. Repeatable

      --plugin-timeout <SECONDS>
          Seconds a plugin may run per package before it is killed
          
          [default: 60]

      --frozen
          Verify remote imports against `ridl.lock` without fetching or regenerating it (CI mode, ADR-0002 §7)

      --deployment <NAME>
          The deployment to carry in each codegen request. With one deployment in the workspace it is selected without this flag; with several, none is carried unless named

  -h, --help
          Print help (see a summary with '-h')

It writes the same artifacts as ridl build — and ridl.lock under the same [imports] condition — under the --out-dir you must now name explicitly. --plugin, --plugin-timeout and --deployment are the same three flags as on ridl build, spelled and documented identically. ridlc reads no baseline, so its descriptors and codegen requests carry an empty compatible list; ridl build is the command that fills it:

ridlc build . --out-dir out && find out -type f | sort

out/Cargo.toml
out/cli.demo.rs
out/lib.rs

Exit codes. 0/1/2 in the same shape as ridl build — clean, a diagnostic is an error, or an input/output error such as a missing --out-dir (usage, exit 2) or a workspace that cannot be found (exit 2).

How ridl and ridlc relate

ridlc is the plumbing: two subcommands, check and build, both with a required PATH and no defaults — stable flags meant for CI and build scripts. ridl check and ridl build call straight into ridlc's own library functions and add nothing to the compile itself; what they add is humane defaults (PATH defaults to ., ridl build's --out-dir defaults to out) and, on check only, the baseline desk check described above, which has no ridlc equivalent. On identical input the two render byte-identical diagnostics, confirmed earlier on this page.

ridl baseline, ridl test, ridl fmt, ridl diff, ridl lock, ridl describe, and ridl vendor have no ridlc counterpart at all — ridlc's surface is check and build, full stop, as its own --help shows. Reach for ridl unless you are scripting the compiler directly and want its stable, default-free flags.

Exit codes across the toolchain

This table is this repository's own taxonomy, recorded in ADR-0010: 0 succeeded, or the verdict is affirmative; 1 a real answer that happens to be negative; 2 the tool could not answer at all. clig.dev, which the ADR quotes rather than paraphrases, says nothing about a multi-valued exit code — it treats exit status as a binary success/failure signal. ridl diff's breaking-change exit 1, ridl fmt --check's would-reformat exit 1, and ridl test's evaluation-fault exit 1 rest on the external diff(1)/grep(1) convention of a specific non-zero code being part of the answer, not on any clig endorsement of it — clig is silent here, not permissive.

Exit code 1 means something different in almost every row: for ridl diff it is the breaking verdict, a statement about the change, not a failure of the tool; for ridl test it is a test failure — a self-corpus problem or an evaluation error, where a suspect finding is not enough to fail the run; for ridl check, ridl build, and ridl baseline it is an ordinary diagnostic error; for ridl fmt it is would change or unparsable. Reading a bare $? of 1 without knowing which subcommand produced it says nothing on its own.

Exit code 2 is the one genuinely shared meaning — an input the command could not use at all, including ridl fmt's missing or unreadable path since ADR-0010 closed the gap documented under ridl fmt above. A clap-level usage error — a missing required argument, an unrecognized flag, or no subcommand at all — is also exit 2 on both binaries, which happens to agree with the applications' own convention rather than being one of their exit paths:

ridl check --bogus-flag

error: unexpected argument '--bogus-flag' found

  tip: to pass '--bogus-flag' as a value, use '-- --bogus-flag'

Usage: ridl check [OPTIONS] [PATH]

For more information, try '--help'.

--help itself, on any subcommand of either binary, always exits 0 — and so does --version/-V, covered above.

Seven of the subcommands that take a path also share a lesser-known gap: issue driftsys/ridl#196 records that when the workspace root itself is unreadable, ridl check, ridl build, ridl baseline, ridl lock, ridlc check, and ridlc build all report error: no `ridl.toml` found at or above `<path>` — exit 2 is right, the cause is wrong, confirmed directly against this build — and when a subdirectory nested inside an otherwise-readable workspace is unreadable, the same six report a bare error: Permission denied (os error 13), naming no path at all, also confirmed directly. ridl test reaches the same code path and wraps it with the top-level path it was given (error: <path>: no ridl.toml found… in the first case, error: <path>: Permission denied… in the second — also confirmed directly), so it names a path but the wrong one in the second case: the workspace root, not the subdirectory that actually failed. ridl fmt is the one subcommand that names the actual cause in both cases (see above); ridl diff names it only when the unreadable directory is the argument passed to it directly, not one nested inside a readable argument.

Lints

A lint is a diagnostic that a project can turn off, report at a different severity, or turn into an error. Every warning and every info diagnostic in the catalogue is a lint: each has a stable kebab-case name, and its catalogue severity is its default level, unless the table at the end of this page gives its default as allow. A lint that is allow by default is reported only when a project sets its level. An error diagnostic is never a lint, and its severity cannot be changed.

The lint name appears in every report of a lint diagnostic. The JSON report of ridl check --format json carries it in the lint field, and the text report adds a note after the snippet:

warning[TYPL-102]: `float` without both a range and a `step`
  ┌─ ./demo.ridl:3:15
  │
3 │ type Broken : km/h [250.0..0.0]
  │               ^^^^
  │
  = lint: `unbounded-float` (set its level in `[lints]` in ridl.toml)

Levels

A lint has one of four levels:

• allow removes the diagnostic from the report.
• info reports the diagnostic as an info.
• warn reports the diagnostic as a warning.
• deny reports the diagnostic as an error. In ridl check, ridl build, ridlc check and ridlc build, an error makes the command exit 1, so a lint at deny fails the run the same way any other error does.

No lint defaults to deny.

The [lints] table

A level is set in the [lints] table of a ridl.toml. Each key is a lint name and each value is one of the strings allow, info, warn or deny:

[lints]
missing-timing = "deny"
shared-error-type = "allow"

A package manifest and a workspace manifest both accept the table. There is no command-line flag that changes a level and no source attribute that changes a level: a CI that wants stricter checks commits the levels to the manifest, so the editor, the command line and an agent see the same levels for the same entry point.

The level of a lint for a package is resolved key by key, and a later source replaces an earlier one:

1. the default level from the table below;
2. the [lints] table of the workspace root manifest, when the package is a workspace member;
3. the package's own [lints] table.

A diagnostic takes the levels of the package whose directory contains the file of its primary span. In a workspace, the root's [lints] table covers the whole directory tree of the root: a file under the workspace root that no member contains, and the root ridl.toml itself, take the root's levels. A file outside the directory tree of the entry point (the standard library, a fetched import, an editor buffer outside the project) uses the default levels, so a project's [lints] never applies to code outside its directory. When there is no manifest at all, for example ridl check on a single file outside any package, the default levels apply.

A member loads its workspace. Running ridl check on a workspace member or on a file inside a member, opening an editor on a member, or passing a member as the path of the MCP tool ridl_check loads the workspace whose members lists the member. The workspace root's [lints] table applies to the member, and the member's own table is applied over it, as in a check from the root. The [defaults] keys and [imports] behave the same way. The command reports only the diagnostics of files under the member; check from the workspace root to see every member's diagnostics. A package that no workspace lists stays standalone, and the search for a workspace stops at the first [workspace] manifest and at a directory that holds .git.

Known limitations of the language server. The language server reads the [lints] tables once, when it loads the workspace: at start, or when the first file is opened. An edit to a [lints] table takes effect in the editor after the server restarts. The language server publishes the diagnostics of every loaded member, also when the editor is opened on one member.

Where levels apply

Levels apply where diagnostics are reported to a person or an agent:

• ridl check, including the desk check against a baseline;
• ridl build, which stops before it writes any artifact when a lint is at deny;
• ridlc check and ridlc build;
• the language server;
• the MCP tool ridl_check.

Every other command reports the severities the emit sites chose: ridl diff, ridl test, ridl baseline, ridl lock, ridl vendor, the MCP tool ridl_diff and the MCP lookup tools. A lint at deny never makes one of them fail. The text note that names the lint still appears in their output. A lint that is allow by default is left out of their output, as it is everywhere else.

Mistakes in [lints]

A mistake in the table never stops a check. Each of these raises MANI-010 (unknown-lint, a warning) on the entry, and the entry is ignored:

• the key is not a lint name, which includes a diagnostic code written as a key (RIDL-100 = "deny") and the name of an error code, which has none;
• the value is not a string;
• the value is a string other than allow, info, warn or deny, which includes a level with the wrong case ("Deny");
• lints is not a table.

MANI-010 is itself a lint, so the table can set its level.

The lints

vendor-source-not-loaded (MANI-018) is raised in standalone mode only; a workspace has no such warning.

bound-above-transfer (TYPL-116) reports a string bound above 4,032 characters or a bytes bound above 16,128 bytes, on the bound. payload-above-ceiling (RIDL-150) reports a payload whose largest encoded size, in an encoding that the workspace manifest enables, is above 16,256 bytes or has no finite bound. It reads the encodings from every [backend.<name>] table of the workspace manifest, as one set, and checks FlatBuffers when that set is empty, which is the case for no table and for tables whose encodings lists are all empty. It reports on the interaction that carries the payload, so a type that no interaction carries is not reported. A fixed is provisioned and never in flight, so it is not checked. A query whose reply is a fallible T | E is checked through both types, and the larger problem is reported. Both messages say that the payload ceiling is 16,256 bytes and that the codecs do not yet enforce it (driftsys/ridl#996). Both default to warn, and a package can set either to deny. The limits are stated in ADR-0030.

[limits] in a unit's ridl.toml sets a payload limit below the ceiling for an interaction. RIDL-151 (a payload above its declared limit or with no finite bound) and RIDL-152 (a [limits] entry that names no interaction of its unit) are errors, so they have no lint name and no level in [lints]. RIDL-151 runs only where an entry gives the limit; where none does, payload-above-ceiling alone applies. The table and the codes are described in the CLI reference and in ADR-0030.

payload-above-ceiling is raised by ridl check and ridl build. The language server does not run it, so it does not appear in the editor. It skips a package that has an error that stops ridl build writing artifacts, or that references a package that has one, and still reports on the other packages of the workspace. An RSDL-7xx error does not count, because a build still writes code after it. An error in no package source file, such as a manifest error, skips every package.

podbuf-padding-order (RIDL-156) reports a struct whose declared field order lays out in a larger podbuf head than the same fields sorted by descending alignment, with declaration order kept among fields of equal alignment. The message names both head sizes and the saving order. It runs only when a [backend.<name>] table of the workspace manifest lists podbuf in its encodings, and only in ridl check, because it reads the published baseline and ridlc does not. A struct is released when a snapshot under .ridl/baseline/ (or under the --baseline path) declares it, and a released struct is never reported, because its order is part of its wire format. With no baseline, every struct is unreleased. The order is reported only when it is strictly smaller than the declared order, so a struct that no order improves draws nothing. The level is info by default.

Setting ordinal-changed to allow makes ridl check --baseline report nothing for ordinal changes, so the baseline desk check no longer warns about them.

link-encoding-not-emitted has a per-backend way to silence it, which the [lints] level does not: a [backend.<name>] table that names no encoding — an empty encodings list, or no encodings key at all — declares that the backend emits no codec, and that backend's links are not compared. A backend with no table at all is still compared. See ridl build for the rule in full.

How the design lints' levels were set

inconsistent-unit, duplicate-shape and low-cohesion-interface are workspace design lints: each reports a property of the whole checked workspace rather than of one declaration. Their default levels and thresholds were not chosen by hand. Each check was run over the evaluation corpus under evals/, three workspaces translated from public interface definitions, and every finding was labelled, blind, by two labellers, one of them a rule-based script, with the maintainer deciding every disagreement. A check's precision is the share of its findings that the labels accept:

• at least 80 %: the lint defaults to warn;
• from 50 % up to 80 %: the lint defaults to info;
• below 50 %: the check does not ship as a lint.

A check with fewer than ten findings on the corpus defaults to info at most, because the sample is too small for warn. A threshold, such as the number of groups low-cohesion-interface reports from, is the least strict value whose precision still meets the level; it is a constant beside the check and is not set in [lints]. Two candidate checks, one on inconsistent abbreviations and one on a package's number of dependencies, fell below the floor and are not lints; the package coupling numbers stay available through the MCP tool ridl_metrics.

The derivation tables, with the precision at every candidate threshold and the recall against the corpus review rubrics, are in evals/calibration/summary.md; the method, the outcome and the recall mapping are recorded in evals/calibration/notes.md. A test pins the number of findings each design lint reports on each corpus workspace, so a change that moves a count is visible in review.

Stability

From release 0.10.0, you can move from one 0.10.x release to the next without changing a source file, a manifest, a script that calls the CLI, a codegen plugin, a program that uses the generated Rust crate, or a deployed peer. This chapter lists what that promise covers and what it leaves out. Release 0.10.0 is published. ridl vendor and the vendor/ layout were added after it, so the promise covers them from the first release that contains them.

What will not change in 0.10.x

• The language. The syntax and the keywords of typl, ridl and rsdl, and the set of sources that compile without an error.
• The manifest. The keys of ridl.toml, their value types, the layout of vendor/ (<manifest root>/vendor/<key>/), and the formats of interfaces.lock and .ridl/baseline.
• Diagnostics and lints. The diagnostic codes, the lint names and the default level of each lint.
• The command line. The subcommands, the flags, the exit codes, and the shape of the --format json and --format sarif output.
• The generated Rust crate. The domain types and the interaction face (Client, Provider, Publisher, Event, serve and Bind).
• The runtime crates. The public API of ridl-rt, ridl-rt-conformance, ridl-loopback, ridl-descriptor and ridl-transport-ws, and the names of their cargo features, podbuf among them.
• The codegen plugin protocol. The messages ridl.ir.v2 and ridl.codegen.v1, as a plugin reads and writes them. An enum of the protocol gains a value only in a minor release, such as 0.11, because a plugin rejects an enum value that it does not know.
• The MCP tools. The tool names and the input and output schemas.
• The wire format. The frame envelope, the attach handshake, the inputs of the catalog hash, the emitted .proto and .fbs mapping, the encoding names, and the offset and size of every field of the podbuf head of every struct and union of the frozen corpus.
• The minimum Rust version. Rust 1.88 for ridl-rt, ridl-rt-conformance, ridl-loopback, ridl-transport-ws (with every cargo feature) and ridl-descriptor, with edition 2021 for the first four and edition 2024 for ridl-descriptor. The generated crate compiles as edition 2021 with Rust 1.88 with every cargo feature on and with default features off, and ridl build writes edition = "2021" and rust-version = "1.88" in its manifest. A 0.10.x release does not raise a minimum. Releases before the one that raised it to 1.88 had a minimum of Rust 1.83.

The minimum covers the crates RIDL publishes and emits, not later releases of their dependencies. A dependency, such as regex, can publish a release that requires a later Rust. Edition 2021 selects resolver 2, which by default selects the newest release without reading its rust-version. To build with Rust 1.88, resolve dependencies with a resolver that reads rust-version: set rust-version = "1.88" in your own package (the emitted manifest of the generated crate sets it), and resolve with CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback set or with resolver 3, or build from a lockfile resolved that way. just compat-check resolves the lockfile of the crate it emits for its test corpus this way before it builds that crate with Rust 1.88.

What may change in 0.10.x

• Additions. A new subcommand, flag, manifest key, field, tool, cargo feature or transport default. A program that does not use an addition is not affected by it. A new flag, command-line argument or MCP tool input on an existing subcommand or tool is optional: a 0.10.x release does not add a required one to an existing subcommand or tool, and does not make an optional one required. A new subcommand or tool may have required ones.
• New lints. A new lint starts at the allow or info level, so it does not fail a build that passed before. TYPL-116 (bound-above-transfer) and RIDL-150 (payload-above-ceiling) are the two exceptions: they start at warn, which does not fail ridl check either, because a payload above the payload ceiling is a defect, even though the codecs do not yet enforce the ceiling.
• Message text. The text of a diagnostic message, of a doc comment and of generated docs.
• Size and budget values. For example the size of a header or the sum that a budget limits.
• Unpublished crates. xtask, ridlc-gen-model and ridlc-gen-rust.

A security fix is the one reason to break a frozen surface in a 0.10.x release. Its reason is recorded in the stability policy.

When a break can happen

A break can only land in 0.11 or a later release, and that release states it. The releases of 0.9.x and earlier are not covered by this promise.

How the promise is checked

The repository checks each frozen surface that has a recorded baseline against that baseline, and a change that removes or alters something a user depends on fails the build. Some parts are promised by policy and not yet checked by a tool: the formats of interfaces.lock and .ridl/baseline, the exit codes of every subcommand other than ridl check, the output of ridl diff, the categories that ridl diff reports, the layouts of the unsubscribe, read and occurrence frames, which no test vector of the frame specification §11.1 shows, the payload-presence rule of §11.1 for a publish under Init or Invalid(Declared) and for a response under reply, which no vector shows, and the codes of §4 and §9.6 that no vector carries, among them the kind values 2 and 5 and the attach encodings 2 and 3, and the ridl-ir types that appear in ridl-descriptor signatures (#1010). A contributor who must change a frozen surface follows the steps in CONTRIBUTING.md, "Changing a frozen surface". The full policy, with the gate that checks each surface and the rules for approving a break, is ADR-0029.

Built. typl has a working toolchain in this repository: the compiler accepts every construct below, and ridl fmt, the LSP server and the code generators are built on it. See what is built.

typl Language Reference

Type Language — the vocabulary layer of the RIDL family: types, ranges, units, constants, and composites, with package namespacing. typl is the root of the family lattice — every other profile (ridl, rmdl, rsdl) builds on the vocabulary typl declares.

Version: 0.1.0

Provenance. This reference re-frames Language Reference §1–§11 of the RIDL Language Reference as the named foundation layer (per the RIDL family concept note, §7.1 Stage 1), incorporates the module system of ADR-0002, and mines the preliminary markspec typl DSL as prior work (see Appendix F). Where this document and the RIDL Language Reference v0.1 overlap, this document is authoritative for the vocabulary layer; the RIDL Language Reference retains authority for interactions.

Table of Contents

1. Scope and Position in the Family
2. Lexical Conventions
3. Packages, Imports, and Visibility
4. Primitives
5. Type Definitions
6. Constants
7. Structs
8. Enums
9. Enum Sets
10. Unions
11. Tuples
12. Collections
13. Comments
14. Doc Comments
15. Conventions
16. Diagnostics
17. Open Questions

• Appendix A — Standard Library
• Appendix B — Full Example
• Appendix C — Standards References
• Appendix D — Codegen Targets
• Appendix E — Formal Grammar (EBNF)
• Appendix F — Prior Work: markspec typl
• Appendix G — Coverage Analysis: JSON Schema and Other Schema Languages
• Appendix H — Glossary

1. Scope and Position in the Family

1.1 What typl is

typl is a units-aware, range-constrained schema language. It answers one question: what is the shared vocabulary? — the types, physical units, ranges, constants, and composite shapes that every other concern in a component-based reactive system describes things with.

typl is the only truly standalone member of the RIDL family. A pure typl package is useful by itself: it generates data types, validators, and documentation across every backend without any interface, behaviour, or deployment content. Every other profile requires typl; typl requires nothing above it.

The name is deliberately -L, not -DL: typl does not describe a system aspect — it is the vocabulary the describing languages are written in.

1.2 The .typl profile

There is one grammar for the whole RIDL family; each language is a profile — a restriction of that grammar selected by file extension. A .typl file accepts type declarations only:

typl declarations are also legal inside every other profile's files and inside .rxdl (the total profile) — a .ridl file may declare the types its interface uses. Profile purity is a policy decision declared per package in ridl.toml, not a grammar limitation (concept note §4).

1.3 Profile boundary decisions

Three boundary calls are recorded here because they were genuinely undecided:

Streams belong to ridl, not typl. A stream <T> is not a data shape — it has no bound, its framing is transport-decided, and it is only valid in interaction position (command/query parameters and returns). That makes it an interaction container, not a vocabulary item. typl owns the element type (type FwBlock : bytes [1..4096]); ridl owns the <T> container. A <T> appearing in a .typl file is a profile error (TYPL-301).

Timing is not typl. Duration literals (10ms, @[20ms..1s]) belong to the family's time core, consumed by ridl/rmdl. The family lexer recognises duration tokens everywhere (one lexer, one registry), but no typl construct accepts them. The stdlib Duration type (a UCUM ms unit type) is unaffected — it is an ordinary unit type.

Interaction kinds are not typl kinds. The markspec-typl precursor attached kinds (signal, event, command, state, stream, config, document) to type bindings. In the family these are split by layer: signal/event/command/query/fixed are ridl's interaction keywords over the interact core; state and stream processing are rmdl territory; config maps to ridl fixed (provisioned constants); document is just a struct. typl keeps only the pure vocabulary kinds: type, const, and the composites. See Appendix F.

1.4 Keyword discipline

The family maintains one reserved-word registry across all profiles (concept note §4.1). Every family keyword is reserved in every profile, including keywords a profile does not accept — signal is not a valid identifier in a .typl file even though .typl rejects signal declarations. This keeps .rxdl unambiguous and keeps identifiers portable across layers.

Keywords used by the typl profile:

package  import  as  internal
type  const  struct  enum  enumset  union
boolean  integer  float  string  bytes
true  false  step  match  reserved  error

Init values use bare = value (§5.8), not a keyword — type Speed : km/h [0.0..250.0 step 0.5] = 0.0, the universal default-value idiom. There is no default keyword (retired) and no init keyword in typl (init is rmdl's, where two equations per flow must be disambiguated). The wire clause and explicit width names (uint8…float64) are deferred to v0.2 (§17.11): range-first inference plus ridl-diff breaking-change detection cover the common case, and forward-compat width-pinning is a niche refinement not worth ten keywords in v0.1.

Keywords reserved family-wide but rejected by .typl (the registry as built, crates/ridl-syntax/src/keywords.rs): ridl's interface, service, signal, event, command, query and fixed (family-neutral, ADR-0012 decision 4); the expr-core words require, ensure; the ridl clause words states and during (general form §4.8); rmdl's model, function, let, init, last, case, if, then, else, when, emit (it also surfaces signal/event in signatures — same concepts, one registry entry each; init is rmdl's alone — the memory-seed keyword, needed because a flow has two equations; typl/ridl express init as bare = value; its ambient time values now/dt are contextual identifiers, not keywords; pre, ->-as-followed-by, node, returns, realizes, and a surface step considered and rejected — models are contract-blind, so no realizes; step remains typl's quantization keyword alone), plus its reserved set merge, current, state, transition, automaton; and rsdl's system, component, distribution, deployment, machine, offers, requires, for (rsdl reference §2 — the rsdl v0.1 words provides, instance, assurance, target, place, on, transport, bundle, time, base, redundant, supervise and degraded left the registry with rsdl v0.2, because no other profile uses them, and each is an ordinary identifier in every profile). (node and returns were considered and rejected by rmdl — never reserved.) The per-profile keyword sections of each language reference enumerate their own additions; the union of those sections is the registry until the platform spec extracts it as a standalone normative list.

The domain spellings are not reserved words — the member-start rule (ADR-0012 decision 4, as amended on 2026-10-11). present, notify, measure, detect, actuate, trigger, the intent operation shapes activate, toggle, select, adjust, dismiss, and the open candidates supply and read are keywords only as the first token of an interface member, in a profile that implements the spelling; no profile does in this release. Everywhere else each is an identifier: the ROS 2 corpus names a field present (evals/corpus/ros2/sensor_msgs/messages.typl) and a query trigger (evals/corpus/ros2/std_srvs/interactions.ridl). An interface member line never starts with an identifier, so a profile that gains a spelling invalidates no source that compiled before. The uxdl words ADR-0012 retired — view, display, input, action, fetch, navigate, scroll, drag, observe, surface, agent — are ordinary identifiers in every profile.

Registry admission test — language, never runtime (family doctrine, audit passed). Every registry entry names a describable property — a shape, an interaction, a requirement, an availability, an occurrence relation — never an execution mechanism. Steps, scheduling, acks, retries, async/await, quarantine, and clock domains are runtime vocabulary: they appear in semantics prose and runtime specs, never as surface syntax. Borderline entries carry their justification where declared (now/dt: logical time is contract-constrainable — rmdl §6.3). A future wire clause (deferred, §17.11) would clear the same bar — wire ABI is contract, not execution. Rejected for leaking: throws, a surface step, library time().

2. Lexical Conventions

The family has one lexer; these conventions bind family-wide. They are restated here because typl is the foundation document.

2.1 Encoding

Source files are encoded in UTF-8 (Unicode 15.0, RFC 3629). Non-ASCII characters are permitted only inside string literals and doc comments.

2.2 Whitespace, Line Endings, Separators

Whitespace (space, tab, CR, LF) is insignificant except as a token separator. A line break is an LF, a CRLF pair, or a lone CR (a CR that is not followed by an LF); a CRLF pair is one line break. A line comment and a doc comment line end at a line break of any of these three forms, a string literal and a regex literal cannot contain one, and diagnostic line numbers count each of them. Newline and comma are interchangeable separators in all block constructs; trailing comma is permitted. There are no semicolons — the ADR-0002 example package veh.common.types; is errata; the grammar has none (concept note §4.1 errata).

2.3 Identifiers

Three ASCII identifier conventions:

Identifiers start with a letter; digits permitted after the first character; underscore only in SCREAMING_SNAKE. Reserved words (§1.4) may not be used as identifiers.

2.4 Integer Literals

Follow ISO/IEC 9899:2018 (C17) §6.4.4.1: decimal, no leading zeros, unary minus for negatives (0, 42, -40).

2.5 Floating-Point Literals

IEEE 754-2019 double precision. Must include a decimal point (0.0, 3.14, -40.0). Scientific notation is not supported in v0.1. NaN and Inf are not permitted in range constraints.

2.6 String Literals

UTF-8 in double quotes. Escapes follow RFC 8259 §7: \", \\, \n, \r, \t, \uXXXX.

2.7 Regex Literals

Enclosed in forward slashes; syntax follows ECMA-262, restricted to the patterns that the Rust regex crate also compiles. Forward slashes inside the pattern are escaped \/.

/^[A-HJ-NPR-Z0-9]{17}$/

A pattern that is not ECMA-262 syntax is TYPL-106. A pattern that is ECMA-262 syntax but that the regex crate cannot compile is TYPL-220. The Rust backend emits a match constraint on a string-backed type as a regex::Regex::new call in the generated code, under the generated crate's validate-pattern feature (on by default), and a pattern that call refuses would fail at run time instead of at build time. A regex constant is emitted as text and is not compiled, but a match that names the constant is, so the constant is checked at its declaration (§6.2).

The ECMA-262 constructs that the regex crate refuses, and that a typl pattern therefore cannot use, include:

• lookaround: (?=…), (?!…), (?<=…), (?<!…)
• a backreference, numbered (\1) or named (\k<name>)
• the control escape \cX, the NUL escape \0, and an identity escape of a letter the regex crate gives no meaning, such as \e, \Q or \k. An identity escape of a letter the crate does give a meaning, such as \a, \A, \z or \pL, compiles in both engines, with the different meanings the table below records
• the empty class [], the negated empty class [^], and an unescaped [ inside a class, as in [[]
• the backspace escape inside a class, [\b]
• a class escape as a range bound, as in [\d-z] or [\w-.]
• a quantifier with no lower bound, such as {,3}, and a { that opens no complete quantifier, as in { alone or a{
• a pattern whose compiled form exceeds the regex crate's size limit. \w and \p{..} are large Unicode classes in that crate, so an ordinary pattern such as ^\w{1,256}$ exceeds the limit, while ^[A-Za-z0-9_]{1,256}$ does not. An artificial pattern such as (a{1000}){1000} exceeds it too.

This list is not complete. The rule is that the compiler compiles the pattern with both engines: a construct not listed here that the regex crate refuses is TYPL-220 too.

TYPL-220 guarantees only that the Rust output can compile the pattern. It does not guarantee that the checker, the Rust output and the output of another backend match the same strings. The checker tests a declared init value against a pattern (TYPL-109) with ECMA-262 semantics, and some patterns that both engines compile have a different meaning in each (driftsys/ridl#597):

2.8 Tokens recognised but not used by typl

Duration literals (500us, 10ms, 1s, 5min, 1h — the five suffixes ridl §2.1 tabulates) and the @ timing sigil are lexed family-wide but rejected by the .typl profile (TYPL-302).

3. Packages, Imports, and Visibility

The module system is ADR-0002's ns core, restated normatively for the typl profile. Four keywords: package, import, as, internal. Distribution (manifest, lockfile, cache) is tooling, not language — see ADR-0002.

3.1 Package Declaration

Every file begins with exactly one package declaration — dot-separated lowercase identifiers:

package veh.common

A package is a directory. All files in the directory declare the same package name, and the name mirrors the directory path relative to the manifest root. Mismatch is a hard error (TYPL-002). The package — not the file — is the unit of visibility, cycle checking, and codegen output.

A package cannot take a name the compiler provides (TYPL-010). Today that is ridl.std alone. Such a package can never be used: every package already imports all of ridl.std implicitly (§3.2) rather than through an import, so the declarations are unreachable under their own name. Where the generated artifact is named for the package, it is overwritten by the standard package's own as well. The reservation is the set of packages the compiler provides, not the ridl. prefix — ridl.stdlib is an ordinary package name.

3.2 Imports

Imports are qualified and named:

import veh.common.Speed
import marine.nav.Speed as MarineSpeed   // alias — collision release valve

Per ADR-0002 there are no wildcards, no relative imports, no re-exports. All three are hard errors.

Errata note. RIDL Language Reference v0.1 §2.2 showed import veh.common.* as a linter warning. ADR-0002, accepted later, bans wildcards outright. This document follows ADR-0002: wildcard import is a compile error (TYPL-003). The RIDL Language Reference should be amended to match.

Implicit imports — always available: all definitions in the same package, and all definitions in ridl.std (Appendix A).

Qualified references — any public definition may be referenced by fully qualified name without an import:

limit : veh.regulatory.SpeedLimit

A type reference that resolves through none of these — not the same package, not ridl.std, not an import, not a qualified name — or that names another package's internal declaration (§3.3) is a compile error (TYPL-011), reported on the written path in every position that takes a type reference.

3.3 Visibility

Two levels. Public is the default; internal is package-private:

struct WheelTick { ... }               // public — visible to importers
internal struct RawWheelFrame { ... }  // package-private

internal may prefix any typl definition (type, const, struct, enum, enumset, union). A public declaration must not expose an internal type in its fields, arms, bounds constants, or backing (TYPL-005) — the contract surface must be fully importable.

3.4 Cycles

Cycles within a package are permitted (mutually referencing declarations are normal). Cycles across packages are a hard error (TYPL-004). Note that recursive composite shapes are separately restricted — see §7.3.

4. Primitives

Five primitive types. Primitives are lowercase keywords — visually distinct from CamelCase named types. They serve as backing types in type definitions; direct use as field types is restricted (§15.3).

4.1 Boolean

No constraint syntax. Serialized as uint8 on transport — 0 = false, 1 = true.

4.2 Integer

Range constraint [min..max] strongly recommended; active profiles may require it. Width is inferred once by the compiler from the declared range and passed to all backends:

Integer domain. Every integer range must fit within [-2⁶³ .. 2⁶³−1] — the int64 domain. Bounds outside it are a compile error (TYPL-111). This closes the u64 hole: the language layer is always int64 (Kotlin Long, C++ int64_t), which cannot hold the top half of full-range uint64. A value that genuinely needs all 64 unsigned bits is modelled as bytes [8].

Language layer — always int64. Transport layer — narrowest wire type that safely contains the range. The resolved width is part of the contract: widening a range across a width boundary changes the wire type, which is a breaking change classified by ridl-diff. (An explicit width floor to pre-empt such flips — a wire clause — is deferred to v0.2, §17.11.)

4.3 Float

Range and step strongly recommended; active profiles may require them. step declares the value's quantization: valid values are origin + n·step, where n is an integer and origin is the declared lower bound, or zero when no lower bound is declared. This is a validity constraint, not a request to round an input. Integer values must lie exactly on the grid. Source literals and resolved constants use exact decimal grid membership. Floating-point constructors and payload validators use the representation rule below and preserve the supplied value rather than normalize it.

Floating-point grid validation uses the type's inferred wire precision. A constructor checks the value projected to that precision and preserves the supplied backing value. A payload validator checks the received representation at the same precision. This makes a constructed value's wire representation valid and keeps a decoded value valid under the same constructor check.

The runtime rule uses binary64 arithmetic over the projected value v. Prepare the phase p = origin modulo step exactly in decimal arithmetic, in [0, step), so shifting a grid by a large origin does not lose its phase. Represent phase and step as a binary64 high part and a residual low part; compensated arithmetic retains those residuals when reconstructing candidate grid points. Subnormal coefficients are scaled by an exact power of two before splitting and computation, then reconstructed values are scaled back.

The adjacent values at the wire precision define v's rounding cell. If the step is smaller than that cell's width, it contains a grid point and v is valid. Otherwise estimate q = (v - p) / step, with q = v / step - p / step as the subtraction-overflow fallback. Check the nearest integer index and its two neighbors, using compensated reconstruction and projecting each candidate to the wire precision. A candidate r admits v when abs(v - r) <= min(4 * epsilon * max(abs(v), abs(p), abs(step)), step / 4), where epsilon is machine epsilon at the wire precision. round selects the nearest integer, with ties away from zero. The quarter-step cap bounds the rounding allowance where the grid is resolvable.

A positive decimal step that underflows binary64 is dense in every finite rounding cell. For a step that overflows binary64, prepare its finitely representable grid points exactly before rounding them and use the same relative rounding allowance. NaN and infinity are never grid values. This is a bounded representation rule, rather than exact decimal arithmetic in the runtime or input normalization; a contract requiring exact decimal grid identity should use the scaled-integer form below.

Width inference is count-based, not step-based. Let N = (max − min) / step + 1 — the number of distinct representable values:

Errata note. RIDL Language Reference v0.1 §3.3 inferred float width from step alone (step >= 0.001 → float32). That rule is unsound: float [0.0..1000000.0 step 0.001] satisfies it but requires 10⁹ distinct values — far beyond binary32's 24-bit significand. The count-based rule replaces it; the RIDL Language Reference should be amended.

Quantized wire form — scaled integers. Because step anchors values at min + n·step, a quantized float is losslessly a scaled integer: raw = (value − min) / step, an unsigned integer whose width follows from N via the §4.2 table. Transports with a scaled-integer convention — CAN/DBC always, SOME/IP optionally per deployment — encode quantized floats this way (factor = step, offset = min). This is exactly AUTOSAR's LINEAR CompuMethod, so the ARXML mapping is direct, and it sidesteps binary-float step fuzziness (0.001 has no exact binary32 representation) on the transports that care most. proto3 and FlatBuffers keep native float/double. See Appendix D.

Language layer — always float64. Transport layer — as inferred above.

4.4 String

A string is a sequence of Unicode scalar values. string [N] bounds the count of scalar values — not graphemes, which are unbounded, and not bytes, which bytes counts. Default [0..256] when unspecified (warning).

The largest advised bound is 4,032 characters. A string of 4,032 characters is at most 16,128 bytes of UTF-8, which with the transport header and the encoding overhead fits in one transfer of 16,384 bytes (ADR-0030 decision 6). A bound above it draws TYPL-116 (warning), reported on the bound. The payload ceiling is 16,256 bytes, and the codecs do not yet enforce it (driftsys/ridl#996).

Every encoding carries a string as UTF-8. The in-memory representation is the target language's own — UTF-8 in Rust, UTF-16 in TypeScript, Kotlin and C# — and the codec converts at the buffer, as every proto and FlatBuffers runtime on those platforms already does. The byte capacity of string [N] is therefore 4·N, which is UTF-16's worst case as well, so UTF-8 costs nothing at the maximum.

Why not UTF-16 on the wire. proto3 string must be UTF-8 and FlatBuffers string is UTF-8, so a UTF-16 wire form means emitting bytes and [ushort] in the schemas. A consumer generated from those schemas would then see an opaque byte field where the contract says text, which breaks ADR-0018 decision 4's rule that interoperability is at the bytes, mediated by the emitted schema.

One consequence is not a projection rule and belongs to a runtime rather than to an encoding: a JavaScript string may hold a lone surrogate, which is not a scalar value and which TextEncoder silently replaces with U+FFFD, so a codec compiled to wasm cannot see the violation. The TypeScript runtime package checks well-formedness at its boundary, before handing the string to the codec, and rejects.

Two rules are an encoding's own rather than this reference's: how a string is stored in an in-place layout, and whether a terminator is guaranteed for a C reader. Both are settled by the podbuf projection record (ADR-0031 decision 5): the tail holds the bytes present followed by one NUL, and the fixed-capacity form is a rejected alternative of that record.

4.5 Bytes

Bound is in bytes; constraint syntax mirrors string but has no match. Default [0..256] when unspecified (warning).

The largest advised bound is 16,128 bytes, the byte size of a string at its advised bound (§4.4). A bound above it draws TYPL-116 (warning), reported on the bound.

4.6 Byte Order

Byte order is not a type property. A typl declaration never states one, and none of the ten inferred widths (§4.2, §4.3) carries an endianness.

Each encoding fixes it: proto3 and FlatBuffers each define their own, and the podbuf projection declares one. A transport that carries a per-signal choice — CAN and DBC's Intel/Motorola selection is the case that raises the question — takes that choice from the deployment, which is rsdl's, and never from the type. The rsdl surface for stating it lands with the rsdl rewrite at v0.2 (§17.9).

5. Type Definitions

The type keyword defines a named scalar — a constrained primitive or a physical unit type. Named types carry domain meaning and are the primary building blocks for all fields.

5.1 Physical Unit Types

A unit type associates a scalar with a unit from the Unified Code for Units of Measure (UCUM) — the unit standard used by OpenTelemetry, HL7 FHIR, and ISO 11240:

type Speed       : km/h  [0.0..250.0 step 0.5]
type Temperature : Cel   [-40.0..125.0 step 0.1]
type Torque      : N.m   [0.0..500.0 step 0.1]
type RPM         : /min  [0.0..8000.0 step 10.0]
type Pressure    : bar   [0.0..10.0 step 0.01]
type Voltage     : V     [0.0..48.0 step 0.1]
type Ratio       : %     [0.0..100.0 step 0.1]

In v0.1 the underlying primitive is float, whatever the literal type of the range (§17.12 records the v0.2 rule, under which integer literals give an integer backing). UCUM expressions are case-sensitive. Because a unit type carries unit, range, and step, downstream layers inherit dimensional checking and range-driven saturation — rmdl computes with Speed, not bare real (concept note §6).

Common automotive UCUM units: km/h, Cel, N.m, /min, m/s2, bar, V, A, W, %.

5.2 Constrained Primitive Types

type Counter : integer [0..65535]
type Gain    : float   [0.0..1.0 step 0.01]
type Vin     : string  [17 match VIN_PATTERN]
type Frame   : bytes   [8]

5.3 String Constraint Syntax

match references a named regex constant or an inline regex literal.

5.4 Bytes Constraint Syntax

No match — bytes are opaque.

5.5 Range Bounds

Ranges are closed (inclusive) on both ends. Either bound may be omitted ([0..], [..255]), in which case the missing bound defaults to the widest value the inferred width allows.

NaN is outside every declared numeric range, including a range with an omitted bound. NaN is also outside every step grid (§4.3); a grid admits only finite values. A numeric range's omitted bound is the widest finite backing value, so a range also excludes infinities. An unconstrained float retains its backing representation's NaN and infinity values. Declaring a range or step therefore changes validity, without globally restricting the float primitive to finite values. These rules apply to named types and inline constraints. The Rust backend enforces them in checked constructors for named scalars and in payload verification for named and inline constraints. Public primitive fields do not validate assignment. The reason is domain membership: NaN has no ordered position in a closed interval and no integer grid index.

Exclusive bounds are not supported, and are not planned. An integer's exclusive bound is written as the closed bound one value inside it. A float's exclusive bound has no definable neighbour: §4.3 derives the width from the range, so "the next representable value" would depend on a width that depends on the bound itself. The forcing case that would reopen this: a published contract whose semantics genuinely require an open interval on a float.

5.6 Width Is Inferred, Never Written

typl v0.1 has no surface syntax for wire width. A range is the only width control an author needs: integer [0..255] is a uint8, integer [0..65535] is a uint16, and the compiler derives the narrowest safe width once (§4.2, §4.3) and passes it to every backend. The ten concrete width names (uint8 … float64) are not keywords, not primitives, and not writable anywhere in a .typl source — writing one is a parse error (there is no production for it).

Range-driven inference has one known hazard: widening [0..250] to [0..300] silently flips the wire type uint8 → uint16 — a wire ABI break from a semantically innocent edit (hardest on FlatBuffers and CAN, invisible on proto3 varint). v0.1 handles this with the ridl-diff gate alone: it classifies every resolved-width change as breaking, so the flip is caught in CI. An explicit width floor that would pre-empt the flip at the source — a wire clause pinning headroom above the boundary — is deferred to v0.2; see §17.11.

A resolved width is part of the contract on every encoding, and part of the memory layout on some. On an encoding with a fixed inline layout there is no vtable to absorb a change of size, so a width change moves every later field. The ridl-diff classification above covers both cases, because it is the resolved width that it compares. A backend that emits a fixed inline layout must therefore treat a width change as a layout break and must not rely on a reader tolerating it.

5.7 Type Identity — Nominal

Every named type is nominally distinct — from its backing primitive and from every other named type, even one with identical constraints. Speed and Torque are both float-backed; they are not assignable to each other, and neither accepts a bare float. A literal is accepted where a named type is expected when it satisfies the type's constraints (this is how const MAX_SPEED : Speed = 250.0 works); a value of another named type never is. There is no implicit conversion anywhere in the family — explicit conversion is expr/rmdl territory, where unit dimensions decide convertibility (§17.5).

Precedent: Ada derived types, Rust newtypes, Haskell newtype. Rationale: nominal identity is what makes unit safety real — structural typing would let a Torque flow into a Speed port because both are "float in a range", which is precisely the class of error this language exists to prevent. Codegen realises nominal types as distinct wrapper types where the target allows (Rust newtype, Kotlin value class) and as documented aliases where it does not (proto3).

A language backend's wrapper type also carries the type's constraints: its value is built through a constructor that checks the range, step and length bounds of §5.1 to §5.5 and reports a violation instead of building the value, beside a constructor that does not check, for a value the payload validator has already checked. A backend may make the pattern check optional. A wire backend emits neither, because a schema cannot refuse a value when it is built. ADR-0013 decision 8 is the rule, and records which backends emit the checking constructor today.

5.8 Init Values

Every type has an init value — the value a consumer holds before anything real arrives (the interaction layer's signal channels start from it; AUTOSAR initValue is the precedent). It is either declared or derived:

Declared — a bare = value suffix, valid on type definitions as well as struct fields. There is no keyword: the value simply follows the constraint.

type Speed : km/h [0.0..250.0 step 0.5] = 0.0

The bare = value form is the family's single init syntax at the vocabulary and interaction layers (typl types, typl struct fields, ridl signal overrides). It carries no keyword — not default (retired) and not init (which belongs to rmdl alone, where init x = value seeds a memory recurrence and the keyword is needed to disambiguate it from the equation).

Derived — when no = value is declared:

For a numeric range with no lower bound whose upper bound is negative, derive the upper bound when no step is declared. With a step, derive the greatest grid point at or below that upper bound, using the zero origin and exact decimal arithmetic. A derived floating-point init must fit the finite backing domain; when no finite grid point is available, the init is not derivable.

A map with a minimum count above one has no derived init: repeating a key's init would violate key uniqueness, and the toolchain does not synthesize distinct keys. Optional map fields without an override remain absent.

A declared init value must have the backing's kind and satisfy the type's constraints, including step (TYPL-109). Floating-point init values and typed floating-point constants must lie within the finite binary64 backing domain. Integer and enum init values may use an exactly integral numeric spelling such as 1.0; an enum value must name a declared discriminant. Constant references are checked after resolution; an unresolved reference is an invalid init. A string literal initializes string or its UTF-8 bytes initialize bytes, with the corresponding character or byte length check. A boolean literal initializes only boolean. The init syntax has no composite or enum-set literal, so a literal or constant override on a struct, union, tuple, array, map or enum set is rejected rather than stored as an untyped scalar. Derived composite inits remain recursive as listed above. A type whose init is not derivable is simply marked so in the IR (TYPL-115, info) — it becomes an error only where a consumer requires an init (e.g. a ridl signal payload, ridl §4.4) and none is declared.

6. Constants

const defines a named compile-time constant — package-scoped, importable, and reusable in range constraints, match patterns, and init (= value) declarations. Higher profiles also use constants in require/ensure expressions.

6.1 Value Constants

package veh.common

const MAX_SPEED      : Speed   = 250.0
const SPEED_LIMIT_EU : Speed   = 130.0
const MAX_GEAR       : integer = 6
const IDLE_RPM       : RPM     = 800.0

SCREAMING_SNAKE naming. The declared value must satisfy the constant's type constraints (TYPL-108). Reuse:

type Speed : km/h [0.0..MAX_SPEED step 0.5]

struct GearState {
  gear : integer [0..MAX_GEAR]
}

6.2 Regex Constants

A const may hold a regex literal, reusable in match constraints. The pattern follows §2.7, and TYPL-106 or TYPL-220 is reported at the constant's declaration, not at each match that names it. The Rust backend emits the constant itself as text, not as a compiled pattern:

const VIN_PATTERN   = /^[A-HJ-NPR-Z0-9]{17}$/
const ASCII_PATTERN = /^[\x20-\x7E]+$/

type Vin   : string [17 match VIN_PATTERN]
type Email : string [1..254 match /^[^@]+@[^@]+\.[^@]+$/]

7. Structs

A struct is a named composite with a fixed, closed set of named fields. There are no additional/unknown properties — a struct is closed by definition (contrast JSON Schema's open-world default, Appendix G). A field name is unique within its struct (TYPL-215): a name identifies one field, so a struct cannot declare two.

struct DriverProfile {
  name     : Name
  speed    : Speed
  override : Speed?     // optional — may be absent
}

7.1 Optionality

The ? suffix marks a field as optional — may be absent, which is distinct from "present with a null value"; typl has no null. Maps to optional in proto3, Option<T> in Rust, T? in Kotlin.

7.2 Field Init Values

A field may carry a bare = value suffix — its init value, the same syntax a type uses (§5.8). There is no attribute block and no keyword; typl carries no other field attribute at the vocabulary layer.

struct RetryPolicy {
  attempts : integer [0..10] = 3
  backoff  : Duration        = 100.0
}

The init value must satisfy the field's type (TYPL-109). require/ensure are expr-core attributes owned by higher profiles and are rejected in .typl (TYPL-303).

7.3 No Recursive Shapes

A struct (or union) must not reference itself, directly or through any chain of composite references. Recursion makes the wire size unbounded, which contradicts the bounded-size guarantee every typl composite otherwise carries. Recursive composite reference is a compile error (TYPL-206). A genuine tree- or graph-shaped payload is modelled with explicit indices into a bounded array.

This is not provisional. The bounded-size guarantee is what the rest of the language rests on: §12 requires an explicit bound on every variable-size collection, §4.3 infers float width from a count of representable values, and an encoding with a fixed inline layout cannot exist at all for a shape whose size is not known at compile time. The forcing case that would reopen it: a published contract whose payload is genuinely tree-shaped and whose depth cannot be bounded at the source.

7.4 Field Identity and Evolution

Tag-based transports (proto3 field numbers, FlatBuffers field ids) need a stable numeric identity per field. typl assigns it implicitly, by declaration order (1-based), for struct fields and union arms alike. There is no explicit = N tag syntax.

That makes evolution discipline part of the language:

• Append-only. New fields are added at the end of the struct or union. Inserting or reordering fields shifts the ordinals of everything after them — a wire break, rejected by ridl-diff.
• Delete by tombstone. A removed field keeps its ordinal slot occupied with reserved:

struct DriverProfile {
  name     : Name
  reserved legacyChecksum      // was ordinal 2 — slot retired, never reused
  speed    : Speed
}

Re-declaring a field under a reserved name is a compile error (TYPL-210).

reserved in an enum body. Both forms are legal there, and they guarantee different things. reserved 3 retires the wire value 3: it is never reused with a new meaning. reserved Retired retires the name Retired: it is never re-declared, and it says nothing about any wire value — a value is retired only by the integer form, because the value a retired name once carried is not recoverable from the source that no longer declares it. Re-declaring either draws TYPL-210. A backend projects a name tombstone where its target has a name reservation of its own — proto3's reserved "NAME"; — and drops it where its target has none, as FlatBuffers does.

• ridl-diff is the enforcement point. Ordinals are fully derivable from source — no sidecar state, no lockfile-assigned numbers. The CI plane (ridl-diff against the previous IR snapshot) rejects reorder, insertion, un-tombstoned deletion, and an append that the backward-compatibility decoder rule below cannot read, in published packages.

• Decoder rule for forward compatibility. The flip side of append-only: a decoder built against version n of a struct, receiving a payload from a version n+k encoder, must ignore unknown trailing fields (and should preserve them when acting as a proxy — the proto3 unknown-field lesson). This is native on proto3/FlatBuffers; on positional transports it requires length-prefixed framing (SOME/IP TLV) or is simply unavailable (CAN) — where unavailable, mixed-version communication is a deployment error rsdl must surface (§17.9).

• Decoder rule for backward compatibility. The other direction: a decoder built against version n+k of a struct, receiving a payload from a version n encoder, finds every field appended since n absent. An absent optional field reads as absent. An absent non-optional field reads as the transport's default, 0, only when the field is a scalar, an enum or an enum set whose type allows the value 0: a range and step that hold 0 (§4.3), an enum that declares a member with the value 0, or any enum set (0 is the empty set). Any other absent non-optional field — a string, bytes, struct, union, tuple, array or map field, or a scalar or enum whose type excludes 0 — has no value to read, and the decoder refuses the payload rather than invent one. So ridl-diff reports appending a non-optional field as breaking unless its type allows 0; the author declares the new field optional (field : T?) instead (driftsys/ridl#598). A type the diff cannot resolve is reported as breaking; ridl diff resolves types against the new snapshot and the built-in ridl.std.

Rationale. Explicit proto-style tags were considered and rejected: they impose a per-field numbering ritual on every struct — including the majority bound to positional transports (CAN, SOME/IP) where the numbers mean nothing — and gaps/vanity numbering must then be linted. Implicit ordinals keep the surface small and the audit trail honest: the wire layout is readable from the .typl file alone. The discipline this demands — append-only with tombstones — is the discipline a contract language wants anyway. Trade-off on record: reordering is legal syntax, and only ridl-diff makes it an error; publishing without the CI gate is unprotected. Judged acceptable because ridlc --frozen + ridl-diff are already mandatory in the ecosystem's CI plane.

8. Enums

An enum is a named set of discrete integer-backed values, for single-value selection:

enum GearPosition {
  PARK    = 0
  DRIVE   = 1
  REVERSE = 2
  NEUTRAL = 3
}

• Backing type is integer, implicit; all values explicitly assigned; values unique (TYPL-203)
• A value name is unique within its enum (TYPL-216): a name identifies one value, so an enum cannot declare two
• First value conventionally = 0 for proto3 compatibility
• String-backed enums are not supported in v0.1; planned for v0.2 (§17.1)

Identity is the value, not the position. An enum value's wire identity is the explicit number it declares, and nothing about it depends on where the value sits in the body. Reordering the members of an enum body therefore changes nothing on any wire; ridl diff reports it as enum_reordered, compatible. This is the opposite of a struct field or a union arm, whose identity is its declaration order (§7.4), and it is why an enum value may be inserted in the middle of a body while a struct field may not.

As built. ridl diff compares enum values and enumset bits by the number each declares. A member whose number changed is reported as member_reordered with its old and new number, breaking. A body whose difference is only order — its values or bits reordered with no number changed, or an enum's reserved list reordered with no entry changed — is reported as enum_reordered, compatible: nothing moves on the wire. The catalog hash covers only the declarations an interface reaches; when an interface reaches the enum or enumset, the order of its values or bits, and of an enum's reserved list, is part of the hash, so the hash changes then.

9. Enum Sets

An enumset is a named bitfield — multiple flags active simultaneously. Backing width inferred from the highest bit position.

An enumset bit's identity is the bit position it declares, not its position in the body, so reordering the members of an enumset body changes nothing on any wire, and ridl diff reports it as enum_reordered, compatible — the same rule as §8's, for the same reason.

9.1 Standalone Form

enumset WarningFlags {
  LOW_FUEL     = 0    // bit 0
  CHECK_ENGINE = 1    // bit 1
  DOOR_OPEN    = 2    // bit 2
  SEATBELT     = 3    // bit 3
}

• Bit positions unique (TYPL-207)
• A bit name is unique within its enumset (TYPL-218): a name identifies one bit, so an enumset cannot declare two
• A bit position is a number with an integer value (TYPL-219): a string, a boolean, a fractional number, a regex, or a constant reference is refused, 1.0 is accepted as bit 1, and a position outside bits 0..63 is TYPL-111

9.2 Derived Form

Derives bit positions from an existing enum — preferred when both single-value and set use are needed:

enum Warning { LOW_FUEL = 0, CHECK_ENGINE = 1, DOOR_OPEN = 2, SEATBELT = 3 }

enumset WarningFlags : Warning

9.3 Width Inference

Language layer — always int64. Transport layer — narrowest inferred.

10. Unions

A union is a discriminated (tagged) union — exactly one arm active at any time:

union SensorResult {
  ok  : SensorReading
  err : SensorFault
}

• Arms reference named types only — primitives not permitted directly (TYPL-204)
• An arm name is unique within its union (TYPL-217): a name identifies one arm, so a union cannot declare two
• Untagged unions and intersections (JSON Schema anyOf/allOf) are deliberately not supported — see Appendix G
• Maps to oneof in proto3, union in FlatBuffers, sealed class in Kotlin, Rust enum

10.1 Error Types

The error modifier marks a named composite as failure vocabulary:

error enum DiagError {
  FILTER_INVALID = 0
  STORAGE_BUSY   = 1
  ACCESS_DENIED  = 2
}

error struct CalFault {          // data-carrying failure
  code   : integer [0..255]
  detail : Message
}

error union ServiceFault {       // composes error types — all arms error-typed
  diag : DiagError
  cal  : CalFault
}

• error is valid on enum, struct, and union only (TYPL-212); an error union's arms must all be error-typed (TYPL-214)
• An error type is otherwise an ordinary type — package-scoped, importable, nominally distinct, usable wherever data is legal (a fault-log struct may contain one; a signal may publish one). The marker adds exactly one bit of meaning: this shape describes a failure
• Codegen realises error types with the target's error material where it exists (Rust std::error::Error impl, Kotlin sealed failure hierarchies) and as plain data elsewhere

10.2 Result Unions

A union mixing error and non-error arms is a result union and must have exactly two arms — one success arm (any non-error type) and one error arm (an error type). Anything else that mixes the two kinds is malformed (TYPL-213). Several failure kinds compose into one error union before entering the result union.

union CalOutcome {
  ok  : CalReport
  err : CalFault
}

A result union is the family's Result<T, E> — achieved without generics, consistent with the no-parametric-types decision. In pure typl a result union is simply a union; the interaction layer (ridl §10.1) recognises it at interaction positions and maps the error arm onto transport-native error channels. This is the family's entire functional-error mechanism: failure is data, declared once in the vocabulary — there is no throws, no exception, no second channel anywhere in the family.

11. Tuples

A tuple is an anonymous composite of named fields used inline — as struct fields at the typl layer; higher profiles additionally use tuples as query returns (ridl §7.1). A tuple is not an interaction parameter type: a parameter is a named type or a stream (ridl §6.1, §7.1).

struct SensorBounds {
  range : (min: Speed, max: Speed)
}

• Fields are always named — positional access is not permitted
• A field name is unique within its tuple (TYPL-215), as in a struct (§7)
• The empty tuple () is the unit type (its interaction role is defined by ridl)
• The same tuple shape used in multiple places draws a linter warning: extract a named struct (TYPL-205)

12. Collections

Collections are finite, bounded aggregates. All variable-size collections require explicit bounds — no defaults, no exceptions (TYPL-201/202).

12.1 Array

readings : [Speed; 8]          // fixed — exactly 8
faults   : [FaultCode; 0..32]  // bounded — 0 to 32

12.2 Map

Keys must be a named string type or primitive. Each key occurs at most once in a map; a payload containing duplicate keys is invalid. Equality is value equality in the key's declared type, including floating-point equality (+0.0 and -0.0 compare equal; NaN does not compare equal to itself). Validation must reject duplicates rather than choose which entry to retain:

metadata : [Label : Name; 0..32]
sensors  : [Label : Speed; 1..8]

A bare string or bytes key takes §4.4–§4.5's [0..256] length default, with TYPL-103, the same as every other position — §15.3 keeps a bare string/bytes out of a field position, but a map key is not one, so the default applies there instead. A key therefore always carries a length bound, which is what lets a projection state a finite size for the map.

A map has no declared entry order, and typl defines no canonical payload encoding. A map is the only typl construct whose ordering is free: an array is ordered, a struct field and a union arm are identified by ordinal (§7.4), and an enum value and an enumset bit carry explicit numbers (§8, §9). So a bit-reproducible byte sequence — what a signed payload, a content hash or a replay plane needs — is a property of an encoding and of the frame that carries it, not of the type. The rule that fixes it, including the entry order a map serialises in, belongs to the frame specification and to each projection record (§17.10).

12.3 Bound Rules

The stream container <T> is the deliberate exception to boundedness and lives in the ridl profile (§1.3).

13. Comments

Discarded by the compiler.

// line comment
/* block comment — nesting not supported */

14. Doc Comments

A doc comment documents the next named declaration or member, called its carrier. It is processed by documentation generators and editors and has no semantic effect: the catalog hash clears every doc field, and ridl diff classifies a change to one as DocOnly. No blank line may separate a doc comment from its carrier (TYPL-404). The decisions behind this section are ADR-0026.

14.1 Syntax