Introduction to Crucible
Relevant source files
The following files were used as context for generating this wiki page:
Crucible is a service framework that generates Rust servers, native client SDKs, and infrastructure packages from .cru models. It provides a shared model layer that preserves HTTP bindings, unions, modeled errors, and idempotency tokens across all supported languages.
Sources: README.md:3-7, AGENTS.md:5-7
System Architecture and Pipeline
The Crucible pipeline transforms high-level models into production-ready code through several distinct stages. The frontend lexes and parses .cru files before lowering them into a shared Intermediate Representation (IR).
Data Flow and Lowering
- Crucible Language: Developers define APIs using the Crucible modelling language.
- Lowering to IR: The
crucible-langcrate parses the source and lowers it to the IR defined incrucible-ir. - Validation: The framework performs shared analyses and validation on the IR.
- Code Generation: Target-specific generators (e.g.,
crucible-codegen-rust,crucible-codegen-go) read the IR to produce SDKs and server bindings.
Sources: AGENTS.md:43-51, AGENTS.md:92-94
The diagram shows the transformation from raw model source to final generated artifacts.
Repository Boundaries
Crucible organizes its functionality into specialized crates. Each crate owns a specific part of the lifecycle, from modelling to runtime execution.
Key Crates and Responsibilities
| Crate | Responsibility |
|---|---|
crucible-server-runtime-rust | Orchestrator, request pipeline, validation, and hosting (HTTP/Lambda). |
crucible-wire | Shared operation descriptions, modeled errors, and body readers/writers. |
crucible-ir | The lowered IR format, shared analyses, and release snapshot format. |
crucible-lang | Lexer, parser, name resolution, and lowering logic for .cru files. |
crucible-codegen | Shared logic for native client selection and stable output publication. |
crucible-build | Cargo build scripts for compiling models and exporting clients. |
Sources: AGENTS.md:31-57
Command Line Interface (CLI)
The crucible CLI provides tools for developers to manage the entire lifecycle of a service. It supports checking models, generating code, and managing SDK releases.
Core CLI Commands
- check: Loads a model and reports constructs that cannot be generated for a specific target.
- generate: Emits code for a specific target (e.g.,
ts,go,rust,openapi,cdk). - diff: Compares API revisions to identify breaking changes and enforce compatibility policies.
- freeze: Saves a compiled model snapshot as a release to prevent future breaking changes.
- scaffold: Generates implementation stubs for service operations.
Sources: crates/crucible-cli/src/main.rs:25-150, README.md:52-60
Client SDK Generation
Crucible generates native client SDKs for a wide variety of languages. Each generator respects the target language's conventions while maintaining a consistent retry and pagination contract.
Supported Target Languages
| Target | Generator Logic | Key Features |
|---|---|---|
| Rust | crucible-codegen-rust | Complete Cargo SDK with automatic runtime dependencies. |
| Go | crucible-codegen-go | Context-aware clients using net/http and native Go models. |
| R | crucible-codegen-r | Native R packages with S3 models and lazy page iteration. |
| TypeScript | crucible-codegen-ts | Fetch-based ESM packages targeting browsers and Node.js. |
| Python | crucible-codegen-python | Typed packages with both synchronous and asynchronous HTTPX clients. |
Sources: README.md:14-28, crates/crucible-codegen-go/src/lib.rs:5-10, crates/crucible-codegen-r/src/lib.rs:1-5
Generation Rules
- Generators must never read the AST; they only consume the lowered IR.
- Unsupported constructs must trigger a diagnostic against the specific shape.
- Output must be deterministic, typically sorted by shape ID or name.
Sources: AGENTS.md:92-106
Summary
Crucible centralizes API logic in a single model, ensuring that server validation and client behavior remain synchronized across different languages. By strictly separating the modelling language from the intermediate representation, it enables consistent code generation for services, SDKs, and infrastructure.
Sources: README.md:1-10, AGENTS.md:88-91