Package capabilities

A package can only touch the machine through a module of std that does, so what a package can touch is a function of its imports, and the toolchain computes it without running anything. The result is a short list of capabilities: torb publish prints it, the registry derives it again from the archive it receives, records it with the release and shows it beside every version. This page is the table the toolchain reads: which module is which capability, and which names are pure.

Synopsis#

torb publish --dry-run       Prints "capabilities:" for the package's own modules, each with the files that reach it
torb update --accept-capabilities
                             Takes an update that gains a capability, which is refused without the flag
Package page, "Versions"     Every version with its capabilities, and "gained: ..." where it adds one

What it does#

The table#

The toolchain's capabilityOf (compiler/src/package/archive.trb) is the one place that says which module is which capability. A module that is not here is pure. The table lives in the toolchain until std carries it itself.

Every imported name decides#

A capability is reading something, and a type is no reading. use Timestamp from "std/time" puts a point in time into a signature and reaches nothing, while use Clock from "std/time" reaches clock. So the summary looks at each name an import brings in, not at its package: a name reaches the capability of its module, unless it is one of the pure values below. A name that is new in a module is a capability until it is listed here as a value, and a use * as name can reach every name, so it reaches the capability of the module.

The values a capability module answers in and fails with are pure:

std/os re-exports two names of modules that are capabilities of their own, and they reach what their own module does:

What a package page shows#

What is summed up is what a package's own modules import. What its dependencies reach is theirs, and the page of each dependency says so. The registry records the set with each release when it is published, and the package page lists it per version:

• A set is shown as the capability names.
• none is a recorded empty set: the package imports nothing that reaches the machine.
• not recorded is a release published before the registry kept the set. It is never shown as none, because that would be a claim nobody checked, and no gain is flagged against it.
• gained: network marks a version whose set has a capability that the version before it lacks. The version before is the nearest earlier version nobody yanked, so the flag still shows what an upgrade from there adds when a yanked version in between gained it first. The first version, a version that lost a capability, and a version beside one that is not recorded carry no flag.

Examples#

The versions of a package on its page, newest first:

Version  Published   Capabilities               Status
1.2.0    2026-10-20  files  network             available
                     gained: network
1.1.0    2026-10-02  files                      available
1.0.0    2026-09-15  not recorded               available

1.1.0 is not flagged: 1.0.0 recorded nothing to compare against. 1.2.0 gained network over 1.1.0.

Related#

• torb publish - prints the summary and sends the archive the registry derives it from again.
• torb update - refuses an update that gains a capability unless --accept-capabilities says it is wanted.
• torb yank - withdraws a version, which then no longer counts as the one before the next.