Capabilities and frames
The seam between Faber and every way an operating system can implement I/O.
call is Faber's low-level capability call primitive — the boundary
between Faber code and the outside world. It opens a typed conversation
(channel) with a host resource identified by a route string, then
exchanges structured frames (frame) over directional half-streams.
The runtime dispatches each route to the native leaf that serves it, and that
leaf implements the actual I/O — filesystem, networking, console, time,
randomness, or anything else the OS can do.
The call primitive#
call is a keyword, not a function. It opens an opaque conversation
with a route named by an ascii literal and optional opener data:
# Simple materialized call: open, send opener, drain response
let string content ← call 'solum:lege' ("config.toml") ↦ string
# Typed conversation handle for streaming interaction
let channel s ← call 'processus:exsequi' ("ls -la")The route string follows a prefix:verb pattern. Dispatch matches on the
prefix — the leaf that owns a prefix handles all verbs under it:
solum:lege ─┐
solum:modum ─┼─► prefix "solum" ──► filesystem leaf
solum:vincula─┘call is not a foreign function interface. It does not call C
functions, load dynamic libraries, or embed inline assembly. It is a
structured message passing boundary: Faber sends typed frames and receives
typed frames, without knowing whether the answering side runs in-process,
delegates to a system call, or forwards to a remote host.
Frame types#
Five compiler-owned types form the frame system:
| Type | Role | Key surface |
|---|---|---|
channel | Conversation handle — an in-flight bidirectional exchange | Created by call; drained via ↦ T or split into views |
frame<T> | Frame envelope — one structured message in a conversation | Fields: id, call, status, data, created_ms, from, trace |
status | Lifecycle marker enum | request, item, byte, bulk, done, error, cancel |
send<T> | Outbound half-stream — send frames to the provider | da(T), fini() → status |
recv<T> | Inbound half-stream — receive frames from the provider | accipe(), cursor(), exhauri(), fini() |
Using directional views#
# Open a conversation, get directional views
let channel s ← call 'solum:scribe' ("output.txt")
let send<string> out ← s.meus<string>()
let recv<string> input ← s.tuus<string>()
# Send content frames
out.da("line one")
out.da("line two")
out.fini()
# Read response frames
for from input.cursor() const frame {
print frame.data
}
let status inbound ← input.fini()Simple materialization#
For the common case — open, send opener, drain all response frames into one
value — channel ↦ T collapses the conversation:
# Read a file: open + drain into string
let string body ← call 'solum:lege' ("config.toml") ↦ string
# Parse JSON from a file
let json data ← call 'solum:lege' ("data.json") ↦ jsonMaterialization uses a type-directed collector: ↦ string
concatenates all inbound frames, ↦ json parses the concatenated
payload, ↦ list<T> collects frames into a list.
Native leaves#
Each effect family is served by a native leaf in the faber-leaf crate
(radix/crates/faber-leaf). The MIR runner and generated Rust share it. Each leaf owns all verbs under its prefix:
| Leaf | Prefix | I/O domain |
|---|---|---|
| filesystem | only:* | Read, write, metadata, directory operations |
| stdio | consolum:* | Console I/O: stdin, stdout, stderr |
| process | processus:* | Process execution, environment, working directory |
| clock | tempus:* | Time: now, monotonic, sleep |
| entropy | aleator:* | Randomness: floats, integers, bytes, uuid |
| tcp | caelum:* | TCP listen, connect, accept, read, write |
| http | http:* | HTTP client calls |
| websocket | websocket:* | WebSocket connect, accept, send, receive |
A route that no leaf serves is refused at run time. Faber code can also
answer a route itself with an @ call 'prefix:name' handler on a top-level
function.
Layer stack#
Faber source: call 'solum:lege' (path) ↦ string
Compiler: channel open + generic attach (no leaf crate names)
Runtime: route lookup + conversation protocol
Leaf: the filesystem leaf reads the file, returns contentThe compiler emits generic dispatch — it never embeds leaf crate names into generated code. Source names a route; the runtime decides which leaf answers it.
Norma wrappers#
Most Faber code does not call call directly. The Norma standard
library wraps common call routes in typed functions:
# Norma wraps call in typed, reviewed functions
fn read(string via) → string {
return call 'solum:lege' (via) ↦ string
}
fn write(string via, string content) → void {
let void _ ← call 'solum:scribe' (via, content) ↦ void
}
fn exsequi(string command) → string {
return call 'processus:exsequi' (command) ↦ string
}These wrapper functions provide type safety, documentation, and error
handling without hiding the fact that I/O crosses the call
boundary. The Norma wrappers live under radix/lib/norma/src/.
References#
radix/docs/design/frame-stream-types.md— full spec for channel, frame, status, send, recvradix/grammar/EBNF.md— thecallexpression and@ callhandlers (Capability Calls)radix/crates/faber-leaf/— the native leavesradix/lib/norma/src/— Norma wrappers over the routesradix/corpus/ad/— channel exempla files