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).

This repository collects the language specifications, the cross-cutting design specs, the architecture decision records (ADRs), the implementation roadmap, and the compiler workspace. Two layers are built: the typl v0.1 preview toolchain (epic E1) — compiler, ridl fmt, an LSP server, and a VS Code extension — and the ridl interface layer over it (epic E2) — the five interaction kinds, timing, contracts, interfaces and services, a TypeScript backend beside the Rust one, and ridl diff. The three remaining description languages are sequenced in the roadmap.

The documentation is published as a book at https://driftsys.github.io/ridl/, rebuilt from docs/book/ by CI on every push to main.

The family

Language	Expands to	Describes	Audience
typl	type language	data — types, ranges, units, constants	data architects
ridl	reactive interface description language	interactions at every boundary — system, person, world (signal / event / command / query / fixed)	service, HMI, and sensor/actuator teams
rmdl	reactive model description language	behaviour — synchronous / functional compute	control / algorithm engineers
rsdl	reactive system description language	architecture — components, wiring, deployment	integrators

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 fifth language — it is the unrestricted file profile plus readable spellings for ridl's non-dispatch interaction families, and it adds no semantics of its own (ADR-0012).

Repository layout

crates/                         The compiler workspace (typl + ridl)
├── ridl-syntax/                Lexer, parser, lossless CST, generated typed AST
├── ridl-core/                  Salsa database, manifest, lockfile, fetch, diagnostics
├── ridl-sem/                   Resolver + checker (per-profile semantic passes)
├── ridl-ir/                    IR v2 protobuf schema + generated types
├── ridl-descriptor/            The catalog descriptor an engine reads
├── ridlc/                      Compiler driver (check / build / emit)
├── ridl/                       Porcelain facade (check / baseline / build / test / fmt / diff / lock / lsp / mcp / describe)
├── ridl-lsp/                   Language server library (`ridl lsp`)
├── ridl-mcp/                   MCP server (ADR-0005 Layer B): `ridl mcp`, nine workspace tools (docs/design/mcp-workspace-tools.md)
├── ridl-backend-rust/          Rust + extern-C code generation over the IR
├── ridl-backend-ts/            TypeScript code generation over the IR
├── ridl-backend-proto/         proto3 schema generation over the IR (a wire backend, ADR-0013 decision 2)
├── ridl-backend-flatbuffers/   FlatBuffers schema generation over the IR (the second wire backend, ADR-0019)
├── ridl-diff/                  The `ridl diff` IR-snapshot compare engine + classifier
├── ridl-fmt/                   The `ridl fmt` engine (rowan-based)
├── ridl-rt/                    The runtime library generated code links (no_std, no dependency)
├── ridl-loopback/              The in-process reference runtime over those ports (ADR-0020 decision 6)
└── ridl-transport-ws/          The WebSocket binding of the frame: a no_std codec and a server over the ridl-rt ports
packages/                       TypeScript packages — ridl-runtime, the wasm codec loader, and ridl-transport-ws, the Deno and browser client of the WebSocket binding
editors/vscode/                 VS Code extension (TextMate grammars + LSP client)
examples/                       Worked examples — a schema and a program against the crate built from it
evals/                          Public evaluation corpus, calibration records and eval tasks (evals/README.md)
xtask/                          Workspace automation (codegen, descriptor-codegen, calibrate; xtask/README.md)
Cargo.toml                      Cargo workspace root
rust-toolchain.toml             The pinned Rust toolchain (ADR-0009)
docs/
├── ROADMAP.md                  Forward plan — epics, stories, the two-step release
│                               plan; what has shipped is in docs/archive/roadmap-landed-record.md
├── BACKLOG.md                  Dated issue priorities, bugs and technical debt
├── book/                       mdBook source (just book) — chapters in docs/book/SUMMARY.md
│                               Its `ridl` examples are compiled by crates/ridl/tests/book_examples.rs
│                               Published to https://driftsys.github.io/ridl/ on every push to main
├── specification/              The normative language references + the family overview
│   ├── ridl-family-overview.md     Entry point: the map, shared doctrines, decision ledger, open questions
│   ├── typl-language-reference.md
│   ├── ridl-language-reference.md
│   ├── rxdl-language-reference.md
│   ├── rmdl-language-reference.md
│   ├── rsdl-language-reference.md
│   ├── family-general-form.md      Cross-profile syntax, typing, and attribute rules
│   └── expr-core-specification.md  The shared contract-term grammar (require / ensure, and rmdl's function layer)
├── wip/                        Pre-ADR drafts and working specs — nothing here is ratified
│   ├── ridl-family-concept.md      Concept note — the family direction (pre-ADR)
│   └── …                           Design notes feeding the roadmap; see wip/README.md
├── design/                      Architecture records — a crate/component, as built
│   ├── ridl-rt.md               The ridl-rt 0.1 runtime library: modules, types, traits
│   ├── ridl-transport-ws.md     The ridl-transport-ws crate: the frame codec and the WebSocket server
│   └── ridl-transport-ws-ts.md  The @driftsys/ridl-transport-ws package: the WebSocket client in TypeScript
├── technotes/                  Informative architecture notes (bind nothing)
│   └── walking-skeleton-architecture.md   The RIDL toolchain, as built
├── archive/                    Superseded documents + landed epic plans
│   ├── ridl-language-reference-v0.1.md   Split into typl + ridl v0.2
│   ├── uxdl-language-reference-v0.1.md   Retired by ADR-0012; its content moved into ridl and rxdl
│   ├── 2026-07-18-e0-walking-skeleton-plan.md
│   ├── 2026-07-18-e1-typl-tooling-spine-plan.md
│   ├── 2026-07-19-e2-ridl-interface-layer-plan.md
│   └── …                           Landed epic plans and design/plan pairs; see archive/README.md
└── decisions/                  Architecture Decision Records
    ├── ADR-0002-module-system.md
    ├── ADR-0004-implementation-sequencing-and-stack.md
    ├── ADR-0005-agent-enablement.md
    ├── ADR-0006-walking-skeleton-execution.md
    ├── ADR-0007-e1-execution.md
    ├── ADR-0008-e2-execution.md
    ├── ADR-0009-toolchain-and-gate-parity.md
    ├── ADR-0010-cli-conventions.md
    ├── ADR-0011-provisioned-constant-keyword.md
    ├── ADR-0012-interaction-boundary-model.md
    ├── ADR-0013-codegen-backend-scope.md
    ├── ADR-0014-ir-encodings.md
    ├── ADR-0015-qos-absorption-and-rpc-bounds.md
    ├── ADR-0016-schema-projection-and-the-name-transform.md
    ├── ADR-0017-proto3-projection-rules.md
    ├── ADR-0018-runtime-core-and-generated-surface.md
    ├── ADR-0019-flatbuffers-projection-rules.md
    ├── ADR-0020-third-encoding-runtime-layering-and-plugin-system.md
    └── ADR-0021-ridl-rt-0.1-api-and-release.md

Where to start

• Writing your first .ridl file? docs/book/getting-started.md — a tutorial over the built toolchain, whose every example is compiled by the test suite.
• New to RIDL? Read docs/specification/ridl-family-overview.md — the map and reading-path guide.
• Want the motivation and the big picture? docs/wip/ridl-family-concept.md.
• Building the toolchain? docs/ROADMAP.md and the ADRs under docs/decisions/.
• Using the tools for agents? ridl mcp serves nine workspace tools, listed in docs/design/mcp-workspace-tools.md.
• Checking how the design lints were set? evals/ holds the evaluation corpus and tasks, and cargo xtask calibrate dumps and derives the calibration; see xtask/README.md.
• Selecting work? docs/BACKLOG.md records the latest priority review of open issues, bugs and technical debt.

Want to watch the generated code run? just demo compiles examples/cabin/cabin.ridl with ridl build --emit rust, then builds and runs examples/cabin/consumer, a small program that links the crate that came out. It prints one line per round trip — a signal, an event, a command and a query through the generated async Client, Publisher, Provider and serve, then the command and the query again through the generated blocking::Client and blocking::serve — over the in-process ridl-loopback runtime. The consumer names the generated face and the runtime and nothing of the compiler that produced them, so it shows what a RIDL interface becomes for the application that uses one.

Development

This repository follows the driftsys house style. After cloning, run ./bootstrap — it installs git-std (conventional commits, versioning, changelog, and git hooks) and prim (the connective-tissue formatter for Markdown/JSON/YAML/TOML), then wires up the repo-local hooks in .githooks/. It also installs the Rust toolchain rust-toolchain.toml pins and, when deno is not on PATH, the Deno release .deno-version pins, and reports any other tool the gate needs — just, rustup, mdBook, jq, flatc at the version .flatc-version pins — that it cannot find.

The task runner is just:

recipe	what it does
just	list the recipes
just fmt	reformat the connective tissue with prim
just check	lint gate — prim fmt --check + prim lint, no writes
just toolchain-check	the running toolchain is the one rust-toolchain.toml pins
just gate-parity	CI invokes every member of just build, and build keeps the members the recipe lists
just fmt-check	cargo fmt --all --check (no writes)
just book-check	mdbook build on a copy — catches a SUMMARY.md mdBook cannot parse
just compile	compile the Rust workspace (--locked)
just test	run the Rust workspace test suite (--locked), and ridl-descriptor's tests with its default features off, and with only dedup on
just lint	cargo clippy --workspace --all-targets -- -D warnings
just wasm-check	cargo check for wasm32, --no-default-features; and ridl-descriptor with its default features off, and with only dedup on, for a target with no standard library, and with its features on for wasm32; and the ridl-transport-ws codec with its default features off, for wasm32 and for a target with no standard library
just compat-check	build and test the packaged ridl-rt and ridl-rt-conformance as edition 2021 with the minimum supported Rust version and as edition 2024 with the rust-toolchain.toml pin; build ridl-loopback, ridl-transport-ws (default features on, off, and with --features descriptor), ridl-ir and ridl-descriptor at that minimum, and the crates emitted for the cabin example and the veh-cluster test corpus (ADR-0021 decision 10)
just demo

CI (.github/workflows/ci.yml) invokes these recipes rather than restating their commands, so there is one definition of each (ADR-0009).

Commits are Conventional Commits, linted against .git-std.toml. See CONTRIBUTING.md and AGENTS.md.

Status

The typl and ridl references are no longer drafts; the version and status of every document are in the family overview. The design is captured; the typl v0.1 preview toolchain (epic E1 — compiler, ridl fmt, LSP, and VS Code extension) is built over the shared grammar and IR, epic E2 added the ridl interface layer over the same grammar and IR v2, epic E6 added rsdl's checks and its lowering to the IR, and the boundary model, rxdl and rmdl are sequenced in the roadmap.

Continuous integration invokes the same just recipes that just verify runs locally, and just gate-parity fails if the two ever drift apart (ADR-0009).

A note on ADR numbering

The ADRs present here are 0002 and 0004–0019. ADR-0001 and ADR-0003 are not in this repository — ADR-0003 ("the family decision") is noted as not-yet-written in the family overview.

License

MIT © driftsys