Language reference

Every Khora construct, one page per topic. If you know the name of the thing you are looking for, this section should answer “what does it look like, and what are the rules?” without reading compiler source or a design document.

Every construct has concrete Khora code here — a construct should never exist only in prose or only in the parser.

Reading it the first time

The pages are lookup-oriented, but they are ordered so that a straight read works. Each opens with what the construct is for before it lists the shapes it accepts.

The syntax of ordinary programs — Expressions, Control flow, Types, Patterns, Generics and Traits.

What makes Khora different — Failures: what may go wrong is in the type. Then Effects and rows and Capabilities: what authority a function needs is in the type too, and the two rows are independent.

Lifetimes and concurrent work — Memory and resources, Concurrency, Sharing.

If you have not built a Khora program yet, start with Getting Started and come back once the toolchain workflow works. Arriving from TypeScript + Effect, Go or Rust, the migration pages map familiar concepts onto these.

The rest of this page is the full index, by topic.

Source and declarations

• Lexical structure — identifiers, row variables, numeric/string literals, interpolation, comments, keywords, and punctuation.
• Declarations — module, import, pub, const, type, derive, fn, extern fn, effect, context, trait, impl, test, and bench.
• Grammar and precedence — compact grammar shapes, operator precedence, and parsing rules that disambiguate similar forms.

Expressions and control flow

• Expressions — literals, calls, fields, records, record update, tuples, lists, blocks, let, assignment, lambdas, |>, ||>, postfix !, catch, handlers, and with.
• Control flow — if, match, guards, while, for, loop, break, continue, return, and typed-failure exits.
• Patterns — wildcard, binding, literal, constructor, record, tuple, guarded, let, for, and catch patterns.

Types and abstraction

• Types — path, unit, tuple, record, mutable-field, variant, function, row, generic, literal, opaque, wrapper, and forall types.
• Generics — type parameters, bounds, const generics, row variables, higher-kinded use, explicit forall, and variance.
• Traits — trait declarations, supertraits, associated types, trait impl, inherent impl, bounds, and derive(...).

Effects, authority, and failure

• Effects and rows — effect declarations and the relationship between with and raises rows.
• Capabilities — handlers, capability rows, postfix/block with, named context, sequential composition, and overrides.
• Failures — raises, raise, postfix !, pattern-based catch, failure translation, attempt, and collecting every reason rather than the first.

Runtime-facing language rules

• Memory and resources — Region, Scope, scoped, acquire, finalizer order, and cleanup on structured exits.
• Sharing — Share, Shared, Changed, Channel, SharedFn, critical-section rules, and cross-fiber values.
• Concurrency — Fiber, Nursery, nursery, bounded_nursery, cancellation, suspension, and structured ownership.
• Traps — checked overflow, bounds failures, process-fatal behavior, backtraces, and exported-call containment.
• FFI — importing with extern fn, exporting with pub extern fn, Ptr, borrowed buffers, and the C ABI boundary.

Working on a program

• Modules and packages — src/bin, dependencies, the lockfile, publishing, and package boundaries.
• The manifest — every table in khora.toml: the required [toolchain] pin, [package], workspaces, permissions, dependencies, lints, and tasks.
• Testing and benchmarks — khora test and khora bench, supplying capabilities to a test, build profiles, and CI.
• Lints — the 21 checks khora check runs, their default levels, and how to set them in [lints].
• Debugging a program — backtraces, debug information, what a debugger can and cannot be relied on for.
• Compatibility and stability — what 0.x promises, what counts as a breaking change, and what 1.0 is waiting for.
• Environment variables — every KHORA_* you may set: where Khora keeps its cache and toolchains, which profile a build uses, and the runtime’s fiber backend.

Where the other sections start

The Reference is the language. Two other sections answer different questions about the same program:

• The Standard Library is what ships with the toolchain — prose for the modules that need it, and generated pages carrying every exported declaration. The Reference gives the syntax of a capability or a fiber; the library reference gives the complete operations of Random, Clock, Shared, Channel, List, the HTTP types and the rest.
• The Cookbook is a whole task, working, end to end — bounded concurrency, a database transaction, decoding untrusted input.