Capability System

Status: stub

Full capability system documentation is planned for Phase 2. This stub covers the concept and key vocabulary.

Spec source: 12_CAPABILITIES.csl

Concept

Capabilities are unforgeable type-level tokens that grant access to hardware resources or privileged operations. To use a capability, you must receive it from a caller who holds one. You cannot create a capability from nothing.

// GpuAllocator is a capability. To allocate GPU memory, you must hold one.
fn create_vertex_buffer(gpu: &GpuAllocator, data: &[Vertex]) -> Buffer<Vertex>;

// You can't call this without a GpuAllocator:
// create_vertex_buffer(/* ??? */, &verts);  // ERROR: where's the capability?

// You get one from the runtime, at startup:
fn main(gpu: GpuAllocator) !io {
    let buf = create_vertex_buffer(&gpu, &verts);
    // ...
}

Why capabilities

The alternative — global mutable GPU state — is what every other GPU API uses. The result is that GPU allocation can happen anywhere, at any time, from any code path. This makes it impossible to reason about allocation budgets, deadlines, or correct ordering without reading every function in the call stack.

With capabilities, you can look at a function’s signature and know whether it touches GPU memory, regardless of what’s inside it.

Key capabilities

Capability	Controls
GpuAllocator	GPU buffer and texture allocation
GpuQueue	GPU command submission
AudioStream	Real-time audio I/O
WindowSurface	Display output
FileSystem	File I/O

Full reference in 12_CAPABILITIES.csl.

See also

• §B.3 Effect System — capabilities as a specialization of effects