Capabilities and effects

Motivation+

Any Rust function can open a file, read the clock or call into C, and nothing in its signature says so. That costs ra-jit three things it wants.+

• Caching. The ra-jit: the function cache can reuse a result only when the function cannot see anything but its arguments. Today it proves that by refusing statics, foreign calls, address exposure and the like, one rule at a time, and asks for #[ra_jit::cache]. A signature that says pure would make the check one line and the attribute unnecessary.+

  No comments yet.

  Comments are not set up yet.

• Sandboxing. Build scripts and proc macros run with the user's full authority (indexable-inc/ra-jit#147: sandbox build scripts and proc macros). With capabilities, a build script gets read access to its crate and write access to OUT_DIR, and can do nothing else.+

  No comments yet.

  Comments are not set up yet.

• Sync and async. Rust writes the same logic twice, once blocking and once async, and libraries pick a runtime for you. If I/O is a capability passed in, the caller chooses how it runs.+

  No comments yet.

  Comments are not set up yet.

It also makes testing honest: a test passes an in-memory filesystem and a fixed clock instead of mocking globals.+

Design sketch+

On the surface, effects: after the return type, / lists what a function uses, as in Effekt (T / Fs, read "T, using Fs"). Several join with +, like trait bounds. Syntax is illustrative; see the open issues.³⁴+

// a crate on the new edition
fn load_config(path: &Path) -> Result<Config, Error> / Fs {
    let text = fs::read_to_string(path)?;
    parse(&text)
}

// No `/`: pure. ra-jit may cache it, and does.
fn parse(text: &str) -> Result<Config, Error> { /* ... */ }

fn main() / Fs + Net + Clock {
    let config = load_config("app.toml".as_ref())?;
    // ...
}

Underneath, capabilities: each effect is a hidden parameter. / Fs lowers to a generic parameter bounded by a trait, so load_config takes an F: Fs and calls through it. Generic, not dyn: each caller's choice is monomorphised and inlined, with no vtable on the hot path.⁵⁴+

fn load_config<F: Fs>(fs: &F, path: &Path) -> Result<Config, Error> {
    let text = fs.read_to_string(path)?;
    parse(&text)
}

A caller that has a capability passes it on implicitly; one that wants to narrow or replace it says so. A test runs the same code against an in-memory filesystem.+

#[test]
fn reads_defaults() {
    let fs = MemFs::from([("app.toml", "port = 80")]);
    with fs {
        assert_eq!(load_config("app.toml".as_ref()).unwrap().port, 80);
    }
}

main receives every capability the platform has. Nothing else is ambient: a function that names no effects cannot reach one, except through unsafe (see the open issues).+

Sync and async from one source+

Zig 0.16 made the same choice from the other side: I/O is an Io value passed in, and the caller picks a blocking or an evented implementation. It dropped the async and await keywords, and code is no longer coloured by how its I/O runs.⁶⁷⁸⁹+

Zig's Io is a runtime interface: a vtable. An evented implementation needs a stack per task, or stackless frames, which Zig does not have yet; the proposals for them are still open.¹⁰¹¹¹²+

ra-jit owns the compiler, so it can decide at compile time. A function that uses an I/O capability is compiled twice when needed: a direct version, which blocks, and a stackless state machine like the one async fn lowers to today. Which one a call gets follows from the capability the caller passes, the way a generic picks its instance. No keywords in the source, no stacks per task, and no function colouring.+

The library side is the sans-IO pattern made a rule: protocol code that never performs I/O itself, driven by whoever holds the capabilities.¹³¹⁴¹⁵+

What it buys+

• Automatic caching: a function with no effects, no unsafe and only pure callees is eligible, with no attribute. One with / Clock or / Rand is not, visibly.+

  No comments yet.

  Comments are not set up yet.

• Sandboxed build scripts and proc macros, granted only what they need.+

  No comments yet.

  Comments are not set up yet.

• One source for blocking and async code; the caller picks.+

  No comments yet.

  Comments are not set up yet.

• Tests without global mocks: pass a fake capability.+

  No comments yet.

  Comments are not set up yet.

• Review: a diff that adds / Net to a parser is visible in the signature, not buried in a call three levels down.+

  No comments yet.

  Comments are not set up yet.

Prior art+

• Zig 0.16.0 release notes, Andrew Kelley, Zig's new async I/O, Loris Cro, Zig's new async I/O, ziglang/zig#25592: std: Introduce Io interface: I/O as an interface the caller passes.+

  No comments yet.

  Comments are not set up yet.

• cap-std: capability-based filesystem and network APIs for today's Rust.+

  No comments yet.

  Comments are not set up yet.

• Sans-I/O and Firezone: sans-IO in Rust networking code: protocols that never do I/O themselves.+

  No comments yet.

  Comments are not set up yet.

• Koka and Effekt: typed effects and handlers, compiled without a runtime for effects; Effekt treats effects as capabilities.+

  No comments yet.

  Comments are not set up yet.

• Unison abilities: abilities in signatures, and pure code identified and cached by hash (Unison: the big idea).+

  No comments yet.

  Comments are not set up yet.

• Scala 3 capture checking: types that track which capabilities a value captures.+

  No comments yet.

  Comments are not set up yet.

• WASI: the host grants capabilities to a wasm module; nothing is ambient.+

  No comments yet.

  Comments are not set up yet.

• OCaml 5 effect handlers: untyped effect handlers on fibers, the stackful alternative.+

  No comments yet.

  Comments are not set up yet.

• Rust effects initiative: the Rust project's work on effect generics (const, async).+

  No comments yet.

  Comments are not set up yet.

Open issues+

References

1. ra-jit: the function cache #[ra_jit::cache], and what makes a function ineligible.
2. indexable-inc/ra-jit#147: sandbox build scripts and proc macros
3. Koka Effect types and handlers, compiled without a runtime for effects.
4. Effekt Effect handlers where effects are capabilities passed in, second-class.
5. cap-std A capability-oriented version of Rust's std: no ambient filesystem or network.
6. Zig 0.16.0 release notes std.Io ships: I/O as an interface value passed in, no async keywords.
7. Andrew Kelley, Zig's new async I/O Why the caller picks blocking or evented I/O by passing an Io.
8. Loris Cro, Zig's new async I/O The same design from the user's side; the end of function colouring.
9. ziglang/zig#6025: async/await/suspend/resume Closed as not planned on 2025-07-15: Zig will not bring back the keywords.
10. ziglang/zig#23446: stackless coroutines as low-level primitives Open. How evented I/O gets stackless frames without async/await.
11. ziglang/zig#23367: restricted function types Open. Lets the compiler know every target of an indirect call.
12. LWN: Zig's new I/O An outside summary of the design and its trade-offs.
13. Sans-I/O Protocol code that never does I/O itself; the caller feeds it bytes and time.
14. Firezone: sans-IO in Rust networking code The pattern in production Rust.
15. quinn QUIC in Rust; quinn-proto is a sans-IO state machine under an async wrapper.
16. ziglang/zig#25592: std: Introduce Io interface Merged 2025-10-29.
17. Unison abilities Effects in signatures, with handlers; pure code is cached by hash.
18. Unison: the big idea Code identified by the hash of its content.
19. Scala 3 capture checking Types track which capabilities a value captures.
20. WASI System interfaces for wasm, granted as capabilities by the host.
21. OCaml 5 effect handlers Untyped effects on fibers: one stack per fiber, no colouring.
22. Rust effects initiative The Rust project's work on const, async and other effect generics.