A research program and reference implementation for provenance-aware semantic reflection in Rust. The repository separates language and compiler proposals from an executable workspace that implements portable runtime semantic contracts—without fabricating compiler reflection that stable Rust cannot provide.
The Cargo workspace version (0.2.0) tracks the executable reference implementation only. Theory, compiler interface, and tooling-projection layers version independently. Matching numbers across layers never imply conformance—see the versioning policy. The latest public packaging release is v0.1.3, published when the workspace version was 0.1.0; the current main branch has since advanced to 0.2.0.
Most “reflection” stories either overclaim what a language can expose or collapse compiler facts, runtime descriptors, and operational topology into one informal blob. Reflective Rust keeps three kinds of knowledge distinct:
| Kind | Meaning | Status in this repository |
|---|---|---|
| Compiler Semantic Graph (CSG) | Compiler-resolved program facts | Exchange schema implemented; no compiler extractor yet—hand-authored graphs are fixtures and must say so |
| Runtime Semantic Projection (RSP) | Opt-in type, capability, runtime, and observation descriptors in a versioned envelope | Implemented: provenance, access policy, validation, canonical JSON, SHA-256 identity, optional Ed25519 authentication |
| Operational Semantic Graph (OSG) | Runtime topology—services, capabilities, providers, contracts, stores, authority boundaries | Implemented as structured descriptors in the protocol crate |
Compiler reflection facilities such as core::meta::Info, semantic queries, reification, generation, and compiler-emitted CSG remain a language and compiler proposal. Stable Rust cannot implement those facilities faithfully. This workspace does not simulate them with fabricated metadata.
Requirements: Rust 1.88 or newer.
The example derives an opt-in runtime descriptor for a normal Rust type, then prints the descriptor as JSON:
cargo run -p reflective-rust-derive --example describe_type
Example source: crates/reflective-rust-derive/examples/describe_type.rs.
The example reports the type name and layout along with each field's name, type, optionality, access level, and available offset. These are runtime descriptor facts produced by the derive macro; they are not compiler-certified semantic reflection.
| Path | Role |
|---|---|
| crates/ | Executable workspace (protocol, derive, CSG schema, conformance, CLI, server, bench) |
| docs/ | Foundations, runtime protocol docs, language proposal, compiler notes, reference |
| Implementation status | What is implemented, tested, proposed, or not implemented |
| Conformance record | Explicit cross-layer conformance record |
| Versioning policy | Independent layer versioning policy |
| scripts/ | Structure and corpus gates used in CI |
| Crate | Role |
|---|---|
| reflective-rust-protocol | RSP envelopes, descriptors, OSG, validation, access projection, JCS, identity, authentication |
| reflective-rust-derive | #[derive(Reflectable)] for opt-in type descriptors |
| reflective-rust-meta | Size/alignment utility and explicit compiler-reflection boundary |
| reflective-rust-csg | Validated CSG exchange schema with mandatory compiler-or-fixture provenance |
| reflective-rust-agent | Radius-bounded, access-aware CSG context slices |
| reflective-rust-conformance | Golden canonical-hash vectors for the implemented RSP protocol |
| reflective-rust-bench | Local measurements without performance claims |
| reflective-rust-server | Minimal read-only protocol discovery endpoint |
| reflective-rust-cli | Minimal protocol discovery command |
- Implemented and tested: opt-in type descriptors, versioned runtime envelopes, validation, canonical JSON and SHA-256 identity, optional Ed25519 authentication, access projection, and structured OSG descriptors.
- Schema implemented; compiler integration absent: CSG exchange types can represent compiler-produced or fixture data with explicit provenance, but there is no compiler extractor in this repository.
- Proposed, not implemented: compiler-level reflection handles and queries, reification, generation, and compiler-emitted semantic graphs.
- Not claimed: production HTTP service, cross-backend compiler conformance, or general performance guarantees.
See the detailed implementation status and conformance record for evidence and boundaries.
This is research software, and architectural criticism is welcome. In particular:
- Is separating compiler facts, runtime descriptors, and operational topology a useful boundary, or does it add unnecessary concepts?
- Which responsibilities belong in derive macros, runtime libraries, and future compiler integrations?
- Which existing Rust patterns or projects should inform—or replace—parts of this design?
Issues and pull requests are welcome, especially when they include a concrete alternative or a minimal reproduction.
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets
python3 scripts/check-structure.py
node scratch/verify-links.mjs
Continuous integration runs the same family of gates on every push and pull request to main (.github/workflows/ci.yml).
- Implementation status
- Conformance record
- Descriptor protocol
- Operational Semantic Graph
- Adoption profiles
- Language proposal (proposal, not implemented reflection)
Layers version independently. The current Cargo workspace version is 0.2.0 for the executable reference implementation. The latest public packaging release is v0.1.3, published when the workspace version was 0.1.0; release tags and workspace crate versions serve different purposes. Neither version claims completion of the language or compiler proposals.
Authoritative policy: docs/meta/versioning.md.
Dual-licensed under MIT OR Apache-2.0. See LICENSE, LICENSE-MIT, and LICENSE-APACHE.
If you use this software, please cite it.
@software{shallbetter_reflective_rust_0_1_3,
author = {Shallbetter, Zachary},
title = {Reflective Rust},
year = {2026},
version = {0.1.3},
publisher = {Zenodo},
doi = {10.5281/zenodo.23290715},
url = {https://doi.org/10.5281/zenodo.23290715},
orcid = {0009-0009-9450-3429}
}
Machine-readable citation metadata: CITATION.cff.
Archival deposit metadata: .zenodo.json.
DOI (this version): 10.5281/zenodo.23290715
Concept DOI (all versions): 10.5281/zenodo.23290630
Zachary Shallbetter
ORCID: 0009-0009-9450-3429