Module cap 

Capabilities: the rights a capability carries, and the operations on one.

What a capability is here

An unforgeable token naming a resource, the rights you hold over it, and the generation it was minted at (CLAUDE.md 7.2). Holding one is necessary and sufficient authority for what it permits. There is no other way to act: no ambient authority, no privilege inherited from who you are.

What this module is, and what it replaced

gs::cap used to be the FILE module - 256 lines whose doc opened “a file as a capability” and which held File and nothing else. So a program needing to acquire, derive or drop an ordinary capability found nothing here and reached into godspeed_sdk, which is the layer a program is not supposed to need. The file half now lives in crate::file.

The rights constants stayed, because they were never file-specific: READ and WRITE are capability rights (CLAUDE.md 7.4), and cap::READ at an fs.open call site reads correctly.

The three properties worth knowing before you use one

Rights only narrow. A copy never carries more than its source, and there is no path back up. duplicate makes an identical copy to hand away; narrowing happens where a capability is minted or granted (CLAUDE.md 7.3), not on the copy.

A capability can go stale. Every one carries a generation, and the resource bumps its own when it dies or is replaced. The next use of a stale capability fails with Error::Unreachable or Error::Revoked rather than reaching the new instance - gs::Error has no EndpointDead variant, so there is nothing else to match. That is not a fault to route around: it is the system telling you the thing you held is gone, and reacquire is how you answer it.

Transfer MOVES. Sending a capability with send_granting removes it from your table. If the send fails it stayed, and it is yours to reclaim; if it succeeded it is not yours any more. Either way the outcome of the send decides what you may do next, so it is never ignorable (CLAUDE.md 8.5).

Structs

Cap

A capability this service holds, by the slot the kernel put it in.

Constants

APPEND

Ask fs for an append-only capability: writes through it may only move FORWARD.

GRANT

Transfer this capability onward (CLAUDE.md 7.4).

READ

Read from the resource (CLAUDE.md 7.4) - a file’s contents, a socket’s datagrams.

WRITE

Write to the resource (CLAUDE.md 7.4) - a file’s contents, a socket’s datagrams.

Functions

acquire

Acquire a SEND capability to a service, by name, from the kernel’s name directory.

acquire_grantable

Acquire a SEND capability that may itself be passed on (GRANT).

duplicate

Duplicate a capability you hold, to hand the copy away while keeping the original.

reacquire

Re-acquire a service by name after its previous instance died.

remove

Drop a capability from this service’s table.

self_grant

A grantable capability to THIS service’s own endpoint, to hand to someone who must reply.