Browse documentation

Reference

Rust profile

Supported Rust constructs, compilation-path differences, and panic and fault behavior.

Septa runs a defined subset of Rust. It includes structs and enums, ownership and borrowing, bounded collections and loops, checked integer arithmetic, exact decimals, and explicit capability calls. It excludes floating point, unsafe code, direct OS access and Rust’s async/await model inside managed code.

Explicit panic! calls and panicking unwrap/expect methods are also rejected. That does not mean execution cannot fail: supported assertions and arithmetic can produce runtime faults.

Where the profile is specified

The binding specifications live under spec/language/ in the source repository. The repository is currently private. This page is the public summary.

Specification What it defines
rust-compatibility-v1.md The Rust meaning that accepted source must preserve, the execution configuration and failure behavior
surface-v0-1.md The stable unit/application constructs, with compatibility tests for each row
original-source-checking-v1.md Supported source forms, types and ownership rules for crate-based projects
original-graph-lowering-v1.md Which checked graph programs can execute and suspend
original-library-graphs-v1.md Crates, modules, imports, dependency identities and the supported manifest format

Read each specification with its amendments. Earlier sections can describe a smaller or retired feature set; floating-point support, for example, has been removed.

The specifications use the internal name original-library graph for the crate-based path explained below. It is not a separate kind or version of library.

Which list applies to my project?

Septa currently has two project formats: unit-based and crate-based. Both take author-written Rust source and can build Septa applications. The names describe how Septa organizes and checks that source. They do not separate application code from library code, and they do not select different arithmetic safety settings.

Unit-based projects

The specifications call this the Unit/application path. A unit is a group of Rust source files with one unit.rs root and a limited set of adjacent module files. An application in this format adds application.toml to configure its behaviors, bindings and routes.

For example, the HTTP watchlist application has these files:

watchlist/
  application.toml
  src/
    unit.rs
    client.rs
    quote.rs

Septa checks these files using the Unit-based column below. This is the format used by the HTTP walkthrough. A “unit” here is a source-code unit, not a unit test.

Crate-based projects

This format organizes the application and its libraries as separate Rust crates. Septa reads the application crate and the source libraries it depends on. Each crate keeps its own modules, imports, visibility and type identities.

You supply each library’s source files without copying its functions and types into the application’s unit.rs. For example, a type defined in pricing still belongs to pricing when an application uses it. Its imports and privacy rules are checked in the library’s own context.

The application and libraries form a source dependency graph: an application imports a library, which may import other libraries. This is the meaning of graph in commands such as effectful graph check. It does not mean a graph database or the network of actors running in your application.

The source must still fit Septa’s supported Rust profile. Septa reads a restricted subset of Cargo.toml; this does not provide arbitrary Cargo dependency support.

The library tutorial creates this structure, with other generated files omitted here:

pricing/
  library.toml
  packages/pricing/
    Cargo.toml
    src/lib.rs
  consumers/example/
    Cargo.toml
    src/lib.rs

packages/pricing contains the reusable library. consumers/example is an application that calls it. A consumer is simply an application using the library; it supplies the entry points and tests through which the library runs. library.toml identifies the library and its consumers.

Both the consumer and its library are checked using the Crate-based column. The project created by effectful new ./pricing --kind library uses this format.

Identify your project’s path

Project files Check or test commands Support column
application.toml and src/unit.rs effectful verify <project>; effectful test <project> Unit-based
library.toml, with library and consumer directories effectful verify <project>; effectful test <project> Crate-based
An application crate with Cargo.toml and src/lib.rs effectful graph check <application>; effectful graph test <application> Crate-based

verify and test select the path from the project descriptor, so their command names alone do not identify it. A library project’s root Cargo.toml can support editors and native Rust checks; its library.toml selects the managed library workflow.

Why the supported constructs differ

These paths have separate source-checking implementations. The crate-based path preserves more Rust project structure, but it does not yet support every expression or framework feature available in the unit-based path. The tables document that current difference; neither column includes everything in the other.

For example, the unit-based path supports assert! and ? on Option; the crate-based path currently refuses both. That is a compiler support limit, not a different meaning for assertions or optional values.

Use the column for your project’s format, including for helpers called by the application. A feature supported in the other column is not automatically available just because the source is valid Rust. Both paths execute accepted code in Septa’s managed runtime; native Rust integration is a separate boundary.

What are the tradeoffs?

The main choice today is between the unit-based application runner’s broader built-in support and the crate-based compiler’s support for reusable Rust libraries.

Concern Unit-based Crate-based
Source organization One source root with a limited, shallow module layout Separate application and library crates, nested modules, privacy and library-owned types
Reusing code Helpers and modules within the unit; restricted imports A library can be used and tested by multiple consumer applications
Rust constructs Broader support for expressions, patterns and framework helpers A narrower supported set; check the tables below before moving code across
External operations The application runner integrates built-in HTTP client, clock, KV and other configured services Consumer serving and watch are available, but durable graph runs do not automatically dispatch those node built-ins; custom capability requests need explicit answers

For a reusable library or framework, the crate-based format provides the source structure needed to share code across consumers. For the current HTTP application walkthrough, the unit-based format provides the documented runner and built-in integration. Check external-operation support as well as Rust syntax before choosing.

Serving an HTTP endpoint for a crate-based consumer does not automatically give its code outbound HTTP access. The listener and the effect adapter are separate integrations.

These formats are not different safety levels or performance tiers. Both use the deterministic core and checked execution. A crate boundary also does not require a separate process or microservice.

Can I mix the formats in one application?

You cannot combine their source feature lists in one compilation. There is no supported switch to compile one helper or dependency with the other profile.

What you want to do Current support
Keep both kinds of project in one repository Yes. Separate project directories make the selection clear. If one directory contains both descriptors, use --kind application or --kind library to select one; this does not combine them
Import a crate-based library directly into unit.rs Adding a Cargo dependency does not enable this. The unit-based compiler retains its restricted import rules
Use unit-only constructs inside a crate-based dependency No. The application and its source dependencies must satisfy the crate-based profile
Run separately compiled components as part of a larger system They can be connected through supported external interfaces, with an explicit integration. There is no automatic cross-format Rust function or actor-call bridge

The runtime can retain both kinds of run on one node. That does not merge their source profiles or make their saved state interchangeable. Each run retains its executable identity and provenance. Serving restrictions also apply: graph commands cannot simply write into a state directory held by an active serving node.

To move code between formats, check it under the destination profile and adapt unsupported forms. Keeping both descriptors or sharing a state directory is not a migration mechanism.

Are the two paths going to be unified?

The documented direction is a shared development workflow. Library projects now use new, verify and test, and their consumers have serving and watch support. You should not need a separate set of everyday tools just because your code is reusable.

See the shared development workflow for an end-to-end walkthrough: project setup, code inspection, editing, verification, cached tests, live development and reviewing evidence. It also explains what remains to be unified across applications, libraries and workspaces.

That work currently retains the two compilers and their support lists. The reviewed development plan does not commit to a single source profile, complete feature parity or a retirement date for the unit-based format. It also does not declare the current split the permanent end state.

Preserving existing programs and stored artifacts is a separate requirement. A future unified authoring model could still keep compatibility with older compiled code. Such a change would need explicit compatibility rules for source and saved state, with migration where required; shared CLI commands alone do not provide them.

The tables below describe support reviewed on 1 October 2026. They list concrete constructs and important limits; the specifications define the exact combinations, methods and saved-value rules. Code that compiles with rustc can still be outside this profile.

Values and expressions

Construct Unit-based Crate-based
Integers and Booleans i64, plus documented i32/usize forms; integer literals, checked arithmetic, %, shifts, compound assignment, comparisons and lazy &&/|| i64, Boolean conditions and comparisons; integer * with checked overflow; checked_add, checked_sub, checked_mul, checked_div, checked_rem. Direct integer +/- remain refused; checked methods return Option<i64>
Exact decimals Decimal, dec!, parsing, constants, comparisons, exact + - *, unary minus, explicit-scale rounding and division Decimal, dec!, ZERO, ONE, from_i64, clone, comparisons and exact + - *. Rounding/conversion methods, unary minus, compound assignment and formatting remain refused
Structs, tuples and enums Struct fields and update syntax; tuples; unit, tuple and named-field enum variants; discriminants Named-field structs; nongeneric enums with unit or named-field variants. Tuple variants, explicit discriminants and recursive by-value types are refused
Option and Result Values, matching and ? on either type Values and restricted exhaustive matches. ? on Result requires the same error type and a supported return context; Option ? is refused
Strings and bytes String/&str values and views; from, to_string, to_owned, clone, append, contains, comparisons and as_str; supported Bytes constructors and UTF-8 conversion Owned String/Bytes literal construction, moves, clone and equality. Bare &str literals, arbitrary string methods and string ordering are refused
Collections Bounded Vec, vec!, push; fixed arrays and indexed reads/writes; OrdMap equality, ordering and fold Owned Vec, new, push, is_empty, plus the framework’s count/at helpers and bounded traversal. This does not include arbitrary Vec methods or general indexing
Constants and formatting Listed primitive/composite const and static forms; format! with supported positional, named, captured and debug formatting General authored const/static items and format! are refused. The specific Decimal constants and dec! above are supported

Arithmetic: stopping execution or returning an error

An i64 has a fixed range. Overflow means the mathematical result does not fit in that range. Septa checks admitted integer arithmetic operators for overflow: an overflowing a * b, for example, stops the affected execution with an Overflow fault. It does not wrap around to an incorrect integer. Known-invalid arithmetic may instead be rejected before execution.

The crate-based path also supports Rust’s checked_add, checked_sub, checked_mul, checked_div and checked_rem methods. These are ordinary Rust integer methods, not a Septa-specific effect. The checked_* spelling is shorthand for this list of methods, not syntax you write in a program.

Each returns Option<i64>: Some(value) contains a valid answer, and None means no valid answer can be represented. Your code can inspect that value and decide what to do next. For example, both of these multiplication forms are supported on the crate-based path:

Inputs supplied at runtime value * factor value.checked_mul(factor)
6 and 7 Returns 42 Returns Some(42)
The largest i64 and 2 Stops execution with Overflow Returns None; your code continues

Both forms detect overflow. The expression you write determines whether overflow becomes a runtime fault or a value your code can handle. Choosing the crate-based project format does not automatically turn arithmetic faults into None.

Here is a pure library helper that turns None into a named application error:

pub enum PriceError {
    OutOfRange,
}

pub fn total_price(unit_price: i64, quantity: i64) -> Result<i64, PriceError> {
    match unit_price.checked_mul(quantity) {
        Some(total) => { Ok(total) }
        None => { Err(PriceError::OutOfRange) }
    }
}

This helper can be called by an entry in an existing crate-based application. Some(total) becomes Ok(total). None becomes Err(PriceError::OutOfRange), which the caller can handle—for example, by rejecting an order whose total exceeds its supported range. No runtime fault is raised or caught in that branch; the method returns an ordinary value, and the helper converts it into an application error.

checked_div works similarly: a zero divisor returns None. It also returns None for the signed overflow case i64::MIN / -1, so None alone does not identify which condition occurred.

Floating point and decimals

f32, f64, floating-point literals and float constants are refused, including in unused code. Decimal / and % operators are also refused. On the unit-based path, decimal division and rounding take an explicit scale and rounding mode. Code needing floating point belongs behind a native integration boundary.

Functions, control flow and ownership

Construct Unit-based Crate-based
Functions and methods Plain helpers with scalar, record, enum, Option and Result results; effectful functions and capability calls Free functions, nongeneric inherent methods and associated functions, including owned, shared and mutable receivers. Mutable receiver calls require pure, disjoint arguments
Branches and patterns if, match, if let, let else, matches!; documented guards, ranges, or-patterns, ref, ref mut and @ patterns if/else and restricted exhaustive matches over Option, Result and authored enums. No general match guards, nested patterns or let else; suspension within branches has additional placement limits
Loops Bounded for, while and loop, with supported labels, break and continue Bounded for/while, with declared bounds up to 64 and inlined nesting up to three levels. Effects in loops, labels, break/continue and same-frame early returns are refused
Early return return; ? on Option and Result, without implicit From conversion return and same-error-type Result ? in specified contexts. Loops, cast bodies, mutable-receiver methods and suspending helpers have further restrictions
Iterators and closures Listed owned iterator operations: into_iter, next, any, all, count, clone, and tested captures General closures and first-class function values are refused; use the supported loops and direct calls
Ownership and borrowing Moves, copies, shared/mutable borrows, reborrows and the listed temporary/view forms Ownership is checked across branches and calls. Borrowed values cannot survive suspension; a durable method’s &mut self refers to checked owned state
Traits and generics Listed derived comparisons and standard container types; arbitrary traits and user-defined generics are outside the stable list Selected Copy, Clone, PartialEq and Eq derives. No general trait dispatch, custom trait implementations or user-defined generics
Modules Depth-one module files, raw names and supported effectful imports Multiple crates, nested inline/file modules, imports, reexports and visibility. Conditional compilation (cfg/cfg_attr), path attributes and block-local modules are refused

A supported container such as Vec<T> does not imply support for arbitrary generic functions. Likewise, selected iterator captures do not establish general closure support.

Framework attributes such as #[effectful], #[durable_server], #[cast] and #[call] connect supported source to execution. Support depends on the compilation path: #[call] is not currently supported in crate-based projects. An attribute does not make unsupported Rust constructs valid. Capability declaration traits define typed operations; they do not introduce general trait dispatch. See the effect system for declarations, inferred effects and authority.

The unit-based list also includes specified Duration, Instant, date, redacted Personal<T> and typed JSON operations. These are finite framework APIs, not unrestricted access to their Rust ecosystem equivalents.

Panics and runtime faults

Managed code does not use Rust panic unwinding. The following are rejected:

  • panic!, todo!, unimplemented! and unreachable!.
  • Panicking Option/Result methods such as unwrap and expect.
  • catch_unwind and custom Drop implementations.

The unit-based profile does support assert! and debug_assert!. Both remain enabled. They are not currently part of the crate-based profile.

Supported operations can still stop execution:

Operation Failure behavior
A failed assertion AssertionFailed
An overflowing arithmetic operator Overflow
A zero divisor in / or Decimal’s div DivisionByZero
An out-of-range supported indexing operation IndexOutOfBounds
Exceeding a declared collection or execution bound A corresponding runtime fault

A fault stops the affected execution. No subsequent expression or effect runs, and the runtime does not invent an Err value or a successful result. Effects completed before the fault are not automatically undone.

Use Result and Option for expected application failures, such as unavailable stock or an invalid request. A failed assertion is an execution fault, not an error that a caller can recover from with match or ?.

The Rust compatibility tests compile the original source with overflow checks and debug assertions enabled, and panic=abort. An assertion that aborts that isolated native comparison is represented as a contained failure in managed execution. Native integration code follows its own build and panic configuration; these profile rules do not guarantee that native code or runtime implementation bugs cannot panic.

Other excluded constructs

Managed source also excludes:

  • unsafe, raw-pointer operations and foreign-function calls.
  • async fn, .await and user-managed futures or executors. See concurrency and async Rust.
  • Direct filesystem, network, process, environment, thread and synchronization APIs. Time, randomness and external I/O go through capabilities.
  • Arbitrary procedural macros, macro definitions and Cargo crates. Only the documented macros, derives and manifest forms are supported.
  • Recursive effectful calls. The crate-based path rejects all recursive call cycles, including pure functions.

Use native Rust integration when a dependency or operation needs Rust features outside the profile.

Values saved across suspension

A value allowed in a pure helper may still be refused in actor state, messages or a saved continuation. Saved values must have supported representations and fit their declared bounds.

A durable-state String, for example, needs #[effectful::cap(N)]. Its bound counts Unicode scalar values, not the bytes counted by Rust’s .len(). Saved vectors, text and bytes on the crate-based path must use the supported capped fields and owner types; arbitrary nesting is not admitted. Capability handles cannot become stored application state.

Supported, refused or experimental?

Status Meaning
Supported A listed construct, within its documented combinations and limits, covered by a compatibility contract and evidence
Refused An invalid or unsupported form rejected with a located diagnostic
Experimental Accepted code outside the stable feature list; compatibility may change

A successful check covers that source and configuration. It does not expand the stable list, prove every runtime input safe or establish that every value can be saved.

A refusal identifies the rejected construct and a remedy. Look up its diagnostic with:

effectful explain <diagnostic-code> --format json

Replace the placeholder with the reported code. The CLI reference lists the command forms for checking and testing each project type.

Search concepts, guides and reference.