Built-ins, no imports required

Primitive types

String methods

List<T>

Mutable homogeneous list. Construct with [a, b, c] or by push. Index with xs[i] (unchecked) or get(i) (safe).

What sorted() accepts. The element type must be one the ordering operators accept: Int, Float, String or Char. Anything else is a compile error naming the type, and pointing at the comparator form:

error: method 'sorted': List<Bool> has no order the compiler can supply;
Bool is not accepted by the ordering operators either. Use sorted_by with
your own comparator to order it.

The compiler-supplied order is total on Float: NaN sorts after every number, so min() answers the smallest real number and max() answers NaN, each agreeing with sorted().first() / sorted().last(). This matters because a sort built on < alone would misplace the non-NaN elements too, and differently on each backend. sorted_by does not get this treatment: there the comparator is yours, and one that is not a total order has undefined results, by the same reasoning that applies to qsort. That is a divergence the language does not paper over, so a sorted_by result is only as backend-stable as your comparator is total.

Ranges: a..b (exclusive) and a..=b (inclusive) carry the transforming and indexed-query methods (map, filter, fold, find, find_index, first, last, get, contains, length, is_empty, to_list), with the same semantics as their List homonyms. The List methods not declared on a Range are sorted, sorted_by, min, max, reverse, enumerate, zip, flat_map and the mutating push / pop; calling one reports type 'Range' has no method '<name>'. Reach them through to_list(). Float endpoints are excluded; a..b..c is a syntax error.

for i in 0..10            # 0, 1, ..., 9
    stdio.println("${i}")

let evens = (0..10).filter(fun (x: Int) -> Bool => x % 2 == 0)

Map<K, V>

Hash map. Construct via new_map() with a required type annotation.

Set<T>

Set of unique elements. Construct via new_set() with a type annotation.

Option<T>

Built-in sum type Some(T) | None.

Result<T, E>

Built-in sum type Ok(T) | Err(E). The ? operator propagates Err in functions that return Result.

JsonValue

Built-in sum type: JNull | JBool(Bool) | JNum(Float) | JStr(String) | JArr(List<JsonValue>) | JObj(Map<String, JsonValue>).

Conversions & panic

Capa has no implicit numeric coercion: Float + Int is a type error. Convert explicitly at the call site.

panic(message) terminates the program immediately: no unwinding, no catch. panic: <message> is written to stderr and the process exits non-zero. The contract is identical on every backend (Wasm and Component Model trap, translated to exit 1).

Python interoperability

Both functions cross the Capa/Python trust boundary and require Unsafe as the first argument. Crossing loses Capa's static guarantees: the Python value can do anything its type allows, with full ambient authority. --manifest marks such functions has_unsafe: true.

fun square_root(unsafe: Unsafe, x: Float) -> Float
    let math = py_import(unsafe, "math")
    return py_invoke(unsafe, math.sqrt, [x])

Capabilities

Stdio

print(s), println(s), eprintln(s) (stderr), read_line() -> Result<String, IoError>.

Fs

Env · Clock · Random

Net

A Net from main is unrestricted; restrict_to(host) returns a fresh Net whose authority is the intersection with {host} (monotonic). get(url) returns Err immediately if the host is outside the restriction set, before any system call.

fun main(net: Net, stdio: Stdio)
    let api = net.restrict_to("api.example.com")
    match fetch(api)
        Ok(body) -> stdio.println(body)
        Err(e)   -> stdio.eprintln("${e}")

Db

SQLite-backed database with path-prefix attenuation (mirrors Fs). query returns the rows as a JSON-encoded array of arrays of strings, so the wire shape is a single form; callers parse with parse_json and project columns explicitly.

Proc

Sandboxed subprocess execution with basename-prefix attenuation. exec takes the command and a JSON-encoded argv tail (for example ["status", "--short"]); stdout is returned as a String. allows checks the basename on a suffix boundary (restrict_to("git") admits git and git-lfs but not gitlab).

Serve

Authority to listen on a TCP address and do I/O on inbound connections. Every other capability reaches out; Serve is the one that is reached. It is deliberately connection-level, not HTTP-level: the trusted runtime binds, accepts and moves bytes, so protocol parsing is ordinary Capa code in a library (see capa_server) rather than trusted-runtime code.

A spec is "addr:port", "addr:lo-hi" or "addr:*", with "*" also accepted as the address. Rules accumulate: a bind must satisfy every rule taken so far, so restrict_to only ever narrows and restrict_to("*:*") on an already-narrowed capability restores nothing. A spec that does not parse denies everything, because silently ignoring a typo would widen authority. Enforcement runs before the syscall, so a denied address or port is never bound, not even transiently.

The model is sequential: one open connection at a time, no threads and no async. A second accept while a connection is open returns Err telling the caller to close first. accept, recv and send are bounded at 30 seconds and return Err on expiry rather than hanging. Honest limits: IPv4 only, addresses matched by exact string equality ("127.0.0.1" and "localhost" are different rules), and the check runs on the port you request, so a rule admitting port 0 admits an arbitrary ephemeral port. On an Err from send the number of bytes already transmitted is unspecified: close the connection rather than retry.

recv is the language's one inbound information-flow source and its bytes are @public; send is a public sink on its payload argument only. The lattice models confidentiality, not integrity or taint: @public on an attacker-controlled request asserts only that it is not a secret whose disclosure the analysis must prevent, and asserts nothing about it being trustworthy or safe to act on. See the information-flow section.

fun echo_once(serve: Serve, conn: Int) -> Result<Unit, IoError>
    let request = serve.recv(conn, 1024)?
    return serve.send(conn, request)

fun main(stdio: Stdio, serve: Serve)
    let local = serve.restrict_to("127.0.0.1:8080")
    match local.listen("127.0.0.1", 8080)
        Ok(_) -> match local.accept()
            Ok(conn) ->
                match echo_once(local, conn)
                    Ok(_) -> stdio.println("echoed")
                    Err(e) -> stdio.eprintln("${e}")
                let _ = local.close(conn)
                let _ = local.stop()
            Err(e) -> stdio.eprintln("${e}")
        Err(e) -> stdio.eprintln("${e}")

User-defined capabilities

Libraries declare their own capabilities with the capability keyword; any type that impls it becomes a valid implementor. A cap-bearing struct may hold built-in caps as fields. Only call / method-call right-hand sides produce fresh capability instances that can be bound; a plain alias let dup = mailer is rejected.

capability SendEmail
    fun send(self, to: String, subject: String, body: String) -> Result<Unit, IoError>

impl SendEmail for SmtpMailer
    fun send(self, ...) -> Result<Unit, IoError>
        return Ok(())

The IoError type

Opaque type for I/O errors, available as the error parameter in Result<T, IoError> and in pattern matching. Its string representation is human-readable; the internal contents are private.

match fs.read("x.txt")
    Ok(content) -> stdio.println(content)
    Err(e) -> stdio.eprintln("error: ${e}")