ALUX Rust

Reusable Design by Meaning infrastructure for typed programs and their interpreters.

ALUX expects many independently published specification crates. This workspace provides the common operation and interface-program vocabulary without centralizing their domain algebras. Each crate has one role: it either defines a meaning, or interprets that meaning for a particular purpose.

Specifications

What a surface means, with no interpreter in it. These depend only on alux-ext and sit at the top level of the repository. The attribute or derive that goes with one is a separate crate, because a procedural macro has to be, and those live under macros/.

Crate		Responsibility
alux-http		HTTP programs and server, no web framework
alux-jsonrpc		JSON-RPC programs, no RPC framework
alux-shape alux-shape-macros		Data shapes, no encoder The derive reading one out of a layout
alux-ext alux-ext-macros		First-order operations and context handles The ext attribute and its macros
alux-sdk alux-sdk-macros		Transformations kept as expressions The macros it exports
alux-traversable		traverse over Option and iterators
alux-bench		What a benchmark measures, no harness

Interpretations

These crates are interpreters, or implementations, of the specifications above. They consume a specification and interpret its meaning for a concrete target, such as a web framework, a document, or a client. Each is published separately under crates/, so specifications can be used without any particular interpreter and the same specification can have several implementations.

Of an HTTP program

Framework-backed execution:

Crate		Interprets a program as
alux-http-axum		executable axum routes
alux-http-actix		executable Actix Web routes
alux-http-rocket		executable Rocket routes
alux-http-warp		executable warp filters
alux-http-poem		executable Poem routes
alux-http-salvo		executable Salvo routes

Framework-free execution:

Crate		Interprets a program as
alux-http-hyper		a hyper service around the direct interpretation
alux-http-direct		direct request and response handling

Documentation and clients:

Crate		Interprets a program as
alux-http-typescript		a TypeScript client module
alux-http-openapi		an OpenAPI document
alux-http-text		documentation or metadata

Shared HTTP support:

Crate		Provides
alux-http-parts		shared multipart reading
alux-http-conformance		shared HTTP scenarios

Of a JSON-RPC program

Crate		Interprets a program as
alux-jsonrpc-typescript		a TypeScript client module
alux-jsonrpc-jsonrpsee		jsonrpsee Methods
alux-jsonrpc-direct		a message handler, no framework

Of a data shape

Crate		Interprets a shape as
alux-shape-rust		a Rust layout
alux-shape-typescript		TypeScript declarations
alux-shape-json		a decision about a JSON value
alux-shape-jsonschema		a JSON Schema document
alux-shape-text		a readable description
alux-shape-term		the term itself
alux-shape-morph		another shape

Of a benchmark

Crate		Measures a stated bench with
alux-bench-criterion		criterion groups and functions
alux-bench-direct		its own runner, saying each case as it finishes

Other interpretations

Crate		Interprets a value as
alux-tokio		bounded Tokio channels

Semantic shape

published domain spec
    -> tiny capability traits and derived extensions
    -> first-order operations
    -> portable HTTP / JSON-RPC programs
    -> separately published interpreter crate

Domain specifications depend on alux-ext and whichever transport program crates they expose. Applications add the interpreter crates they run and configure them.

Documentation

The ALUX programming guidelines teach the method this workspace follows: designing programs by meaning first, in the style of Conal Elliott's Denotational Design, with a concrete path into Rust. Read them for the reasoning behind the rules below.

• DENOTATIONAL_DESIGN.md defines the meaning-first methodology and review rules.
• ARCHITECTURE.md maps those rules to the operation and transport-program algebras.
• AGENTS.md is the compact engineering authority and CI checklist.
• CONTRIBUTING.md describes contribution expectations.

Development

just ci

That runs, in order, just fmt, just build, just clippy, just doc, just test, and just package. Each is also runnable on its own during development. The Justfile holds the full command every recipe stands for.

Publication

Packages are licensed under MIT. Publish and verify them in this order, allowing the crates.io index to update between dependent packages:

1. alux-ext-macros, alux-sdk-macros, and alux-shape-macros in any order
2. alux-ext
3. alux-bench, alux-http, alux-jsonrpc, alux-shape, and alux-traversable in any order
4. alux-sdk, alux-shape-json, alux-shape-text, and alux-shape-typescript in any order
5. alux-shape-jsonschema, alux-http-parts, alux-http-text, alux-http-direct, alux-http-conformance, alux-http-poem, alux-http-actix, alux-http-axum, alux-http-hyper, alux-http-openapi, alux-http-rocket, alux-http-salvo, alux-http-typescript, alux-http-warp, alux-jsonrpc-jsonrpsee, alux-jsonrpc-direct, alux-jsonrpc-typescript, alux-shape-rust, alux-shape-term, alux-shape-morph, alux-bench-direct, alux-bench-criterion, and alux-tokio in dependency order where needed

Cargo cannot fully package later steps against crates.io until the preceding package version is available there.