Standard library

The Khora standard library is written primarily in Khora and ships with the compiler toolchain. It provides the stable vocabulary and cross-package contracts that ordinary programs need without turning every database, telemetry backend, or platform integration into std.

Major areas

The current standard library includes APIs for:

• strings and collections, in std::core;
• JSON encoding and decoding, in std::json;
• files, in std::fs, and processes, in std::process and std::process::shell;
• the environment, in std::env;
• randomness, in std::random;
• clocks and sleeping, in std::clock;
• describing and decoding untrusted input, in std::schema;
• typed configuration, in std::config;
• retries and backoff schedules, in std::resilience;
• civil dates and offsets, in std::time;
• exact Decimal arithmetic, in std::decimal;
• HTTP client/server building blocks, in std::net::http, over std::net::socket;
• TLS, in std::net::tls;
• structured concurrency and shared state, in std::core;
• database capability and row/cell vocabulary, in std::db;
• tracing context and W3C propagation vocabulary, in std::trace;
• structured logging and writing to standard error, in std::log;
• capability permissions, in std::permissions, over the grants in std::permissions::grants that khora build writes out of the manifest.

Four of those are easy to miss:

std::clock holds the Clock capability, and Clock has a sleep — an operation on the capability, so a fake clock is one line in a test.

std::config reads settings out of the environment, types them, and reports every bad key in one pass rather than one restart per key. See the cookbook recipe.

std::resilience holds Schedule, retry, retry_while and repeat. See Retrying a flaky call.

std::schema describes the shape of a value once and decodes it from anywhere. It is the newest, and the one that changes how the others are meant to be used: a Schema<Settings> reads the same settings from the environment, from a request body or from a test fixture, because the description does not know where the bytes came from. Schemas is the model; Decode untrusted input is a program that runs.

Choosing a collection

List<A> is a linked sequence, for ordered transformation and iteration. Vector<A> is a growable contiguous sequence, for accumulation and indexing. Map<K, V> is a mutable hash table; Dict<K, V> is a persistent ordered map.

The language does not change with the choice: ordinary calls, methods, pipelines, lambdas, for and pattern matching work the same over all four. The operations themselves are in std::core.

The mutable ones — Vector and Map — stay fiber-local. Where several fibers need one evolving value, that is a Shared boundary or a capability, not a container passed around; Sharing says why wrapping the type name in a shareable record does not make it safe.

What belongs in std

Khora keeps shared contracts in the standard library and leaves fast-moving implementations in packages. For example, Db, transaction semantics, and database cell types belong in std; PostgreSQL, SQLite, and Cloudflare D1 drivers do not. Trace vocabulary and propagation belong in std; vendor exporters do not.

The same principle keeps the IANA time-zone database out of the compatibility promise while retaining stable date/time/offset types.

std::ai is not part of std. Model inference is the ai package, published alongside postgres and otlp. What it offers is the effect a caller names when it wants a model, so that the provider is the caller’s choice. Name the package as a dependency and import from it.

Generated API reference

This page is the curated entry point; the API reference pages beneath it are generated by khora doc from the /// and //! comments in std/ at the revision being documented. Every exported type, trait, effect, function and constant is there, with its signature and whatever its author wrote about it.

They are checked rather than trusted. khora doc --check runs in the project baseline and fails if the checked-in pages no longer match the source, so a page cannot quietly drift from the declaration it describes.

Two limits worth knowing:

• Almost no example is compiled. A CI job compiles the fenced blocks that declare their own module line, and across the whole of stdlib/api there is exactly one of those out of about 1,100 code blocks. The rest — signatures and fragments — are prose, and can be wrong without anything noticing.
• Type names inside a rendered signature are not links. A signature mentioning Decimal names it but does not link to it. Prose around a signature does link: khora doc renders the [`Name`] form as a working anchor, and there are about a hundred of those, plus an “API at a glance” index at the top of every page.

Use the Language Reference for the language, this section for the library, and the generated pages beneath it for exact declarations.