# Khora

> Khora's bet is that three things belong in the type system together — what a function can *fail* with, what external *authority* it needs, and how its concurrent children are *scoped* — and that a native language can have all three without a borrow checker and without a tracing garbage collector. That combination is the argument; every piece of it exists somewhere else already.

This index covers v0.4, the current stable release. Next covers the unreleased compiler. Read [stable](https://khoralang.com/docs/v0.4/llms.txt) or [next](https://khoralang.com/docs/next/llms.txt).

The [complete documentation](https://khoralang.com/docs/v0.4/llms-full.txt) is also available in one file.
For a smaller file without the generated standard-library API, read the [guide](https://khoralang.com/docs/v0.4/llms-full-guide.txt).

## Overview

- [Khora documentation](https://khoralang.com/docs/v0.4/index.md): Learn the Khora language, standard library, toolchain, deployment model, and production patterns.

## Getting Started

- [Getting Started](https://khoralang.com/docs/v0.4/getting-started/index.md): You can go from an empty directory to a checked, tested, native Khora executable in a few minutes.
- [Installation](https://khoralang.com/docs/v0.4/getting-started/installation/index.md): Install the Khora toolchain once, then use khora to manage compiler versions for all of your projects.
- [Your first Khora project](https://khoralang.com/docs/v0.4/getting-started/first-project/index.md): A Khora package has a khora.toml manifest and source files, conventionally under src/.
- [Editor setup](https://khoralang.com/docs/v0.4/getting-started/editor/index.md): Khora ships one language server as part of the compiler toolchain: khora lsp.

## Language Reference

- [Language reference](https://khoralang.com/docs/v0.4/reference/index.md): Every Khora construct, one page per topic.
- [Lexical structure](https://khoralang.com/docs/v0.4/reference/lexical-structure/index.md): Khora source is UTF-8 text.
- [Declarations](https://khoralang.com/docs/v0.4/reference/declarations/index.md): This page lists the declaration forms accepted at module scope.
- [Grammar and precedence](https://khoralang.com/docs/v0.4/reference/grammar/index.md): This page summarizes the concrete grammar rules that most often matter when reading or writing Khora.
- [Expressions](https://khoralang.com/docs/v0.4/reference/expressions/index.md): Khora is expression-oriented.
- [Control flow](https://khoralang.com/docs/v0.4/reference/control-flow/index.md): Khora's control-flow forms are expressions or block-like expressions.
- [Patterns](https://khoralang.com/docs/v0.4/reference/patterns/index.md): Patterns appear in match and catch arms, local destructuring, for bindings, and other positions that bind or inspect a value.
- [Types](https://khoralang.com/docs/v0.4/reference/types/index.md): Khora is statically typed with inference for ordinary local expressions and explicit annotations where a boundary or ambiguity needs one.
- [Generics](https://khoralang.com/docs/v0.4/reference/generics/index.md): A generic is code written once against a type it does not know, and a bound is what it is allowed to assume about that type.
- [Traits](https://khoralang.com/docs/v0.4/reference/traits/index.md): A trait is what generic code is allowed to assume, and an impl is a type's answer to it.
- [Effects and rows](https://khoralang.com/docs/v0.4/reference/effects/index.md): Khora functions can carry two orthogonal row-polymorphic dimensions in addition to parameters and return values:
- [Capabilities](https://khoralang.com/docs/v0.4/reference/capabilities/index.md): A function that needs to touch the outside world says so in its signature, and the caller has to hand it the means:
- [Failures](https://khoralang.com/docs/v0.4/reference/failures/index.md): Recoverable failure is part of a Khora function type.
- [Memory and resources](https://khoralang.com/docs/v0.4/reference/memory-and-resources/index.md): Khora manages ordinary memory automatically.
- [Sharing](https://khoralang.com/docs/v0.4/reference/sharing/index.md): Khora keeps ordinary mutation fiber-local.
- [Concurrency](https://khoralang.com/docs/v0.4/reference/concurrency/index.md): Start concurrent work with Fiber::spawn.
- [Traps](https://khoralang.com/docs/v0.4/reference/traps/index.md): A trap is an unrecoverable programming error or violated invariant.
- [Foreign function interface (FFI)](https://khoralang.com/docs/v0.4/reference/ffi/index.md): Khora does not define a stable native Khora-to-Khora ABI.
- [Modules and packages](https://khoralang.com/docs/v0.4/reference/modules-and-packages/index.md): A Khora package groups source, dependencies and compiler configuration behind a khora.toml manifest.
- [The manifest](https://khoralang.com/docs/v0.4/reference/manifest/index.md): Every Khora project has a khora.toml at its root.
- [Testing and benchmarks](https://khoralang.com/docs/v0.4/reference/testing/index.md): test and bench are declarations, not a naming convention, and they live beside ordinary source.
- [Lints](https://khoralang.com/docs/v0.4/reference/lints/index.md): khora check runs 21 lints alongside type checking.
- [Debugging a program](https://khoralang.com/docs/v0.4/reference/debugging/index.md): Khora compiles to an ordinary native executable with ordinary debug information, so the tools you already have work on it.
- [Compatibility and stability](https://khoralang.com/docs/v0.4/reference/compatibility/index.md): Khora is 0.x.
- [Environment variables](https://khoralang.com/docs/v0.4/reference/environment/index.md): Khora reads a handful of KHORA_* variables.

## Standard Library

- [Standard library](https://khoralang.com/docs/v0.4/stdlib/index.md): The Khora standard library is written primarily in Khora and ships with the compiler toolchain.
- [Schemas](https://khoralang.com/docs/v0.4/stdlib/schema/index.md): std::schema describes the shape of a value once, and decodes it from anywhere.
- [Decimals](https://khoralang.com/docs/v0.4/stdlib/decimal/index.md): Decimal is exact base-10 arithmetic, and it is deliberately not Float.

## Packages

- [Packages](https://khoralang.com/docs/v0.4/packages/index.md): What ships alongside the language, and how a manifest names it.
- [postgres](https://khoralang.com/docs/v0.4/packages/postgres/index.md): A PostgreSQL client that speaks the wire protocol directly.

## Cookbook

- [Cookbook](https://khoralang.com/docs/v0.4/cookbook/index.md): The Cookbook combines Khora language features and shipped standard-library APIs into complete application patterns.
- [Build an HTTP service](https://khoralang.com/docs/v0.4/cookbook/http-service/index.md): Khora's shipped HTTP router works directly with Request, Response, Router, and shareable handler functions.
- [Build a typed JSON API](https://khoralang.com/docs/v0.4/cookbook/json-api/index.md): Use typed request and response records at the HTTP boundary.
- [Run a database transaction](https://khoralang.com/docs/v0.4/cookbook/database-transactions/index.md): Wrap the body: transaction(fn () => body()).
- [Take work off a queue safely](https://khoralang.com/docs/v0.4/cookbook/taking-work-off-a-queue/index.md): A worker pool is a fiber that reads a job from a channel and does it.
- [Bound concurrent work](https://khoralang.com/docs/v0.4/cookbook/bounded-concurrency/index.md): Structured concurrency tells you who owns concurrent work.
- [Make resource cleanup cancellation-safe](https://khoralang.com/docs/v0.4/cookbook/cancellation-safe-resources/index.md): A resource should register its cleanup as soon as acquisition succeeds.
- [Decode untrusted input](https://khoralang.com/docs/v0.4/cookbook/decoding-input/index.md): Write the type once.
- [Load application configuration](https://khoralang.com/docs/v0.4/cookbook/configuration/index.md): Read every setting at start-up, report every bad one in a single message, and keep the password out of the logs.
- [Retry a flaky call](https://khoralang.com/docs/v0.4/cookbook/retrying/index.md): Somebody else's service is down for four seconds.
- [Test code that uses capabilities](https://khoralang.com/docs/v0.4/cookbook/testing-capabilities/index.md): A capability requirement is an explicit seam for tests.
- [Trace an operation](https://khoralang.com/docs/v0.4/cookbook/tracing/index.md): Wrap an operation in around(tracer, name, fn () => ...) and the span is started before it and finished when it returns, raises, or is canceled.
- [Log, and correlate it with traces](https://khoralang.com/docs/v0.4/cookbook/logging/index.md): A log line is read by a program before it is read by a person: it goes to a collector, gets indexed, and is queried months later by somebody who was not there.
- [Give work a deadline (timeouts and cancellation)](https://khoralang.com/docs/v0.4/cookbook/timeouts-and-cancellation/index.md): There is no timeout function in the standard library.

## Internals

- [Internals](https://khoralang.com/docs/v0.4/internals/index.md): How Khora works underneath: what a reference count costs, how a handler is reached, what a fiber is made of, why a build is reproducible.
- [Memory](https://khoralang.com/docs/v0.4/internals/memory/index.md): Khora has no tracing garbage collector and no lifetimes to write down.
- [Effects and handlers](https://khoralang.com/docs/v0.4/internals/effects/index.md): A Khora signature says what a function needs and how it can fail:
- [Fibers](https://khoralang.com/docs/v0.4/internals/fibers/index.md): A fiber is a Khora computation that can suspend — waiting on a socket, a timer, a channel — and continue later, while other fibers run.
- [The build](https://khoralang.com/docs/v0.4/internals/build/index.md): khora build takes a package from source to a native executable in one process: parsing, name resolution, type inference, exhaustiveness checking, whole-program monomorphization, reference-count planning, LLVM, and a link.

## Deployment

- [Deployment](https://khoralang.com/docs/v0.4/deployment/index.md): Start with Supported targets to see which platforms are actually supported by the current toolchain.
- [Supported targets](https://khoralang.com/docs/v0.4/deployment/supported-targets/index.md): A platform is in one of three states here, and the words mean this:
- [Containers](https://khoralang.com/docs/v0.4/deployment/containers/index.md): Khora's native deployment goal is a small, self-contained executable that does not require a language VM or tracing garbage collector in the container image.
- [Linux](https://khoralang.com/docs/v0.4/deployment/linux/index.md): Linux is a primary native deployment target for Khora services.
- [Cloudflare Workers](https://khoralang.com/docs/v0.4/deployment/cloudflare/index.md): Khora does not yet advertise Cloudflare Workers as a supported deployment target.

## Migration

- [Coming to Khora (migration guides)](https://khoralang.com/docs/v0.4/migration/index.md): These notes map familiar concepts from other ecosystems onto Khora.
- [From TypeScript + Effect](https://khoralang.com/docs/v0.4/migration/from-typescript-effect/index.md): If you know Effect, Khora's motivation should feel familiar: failures and capabilities belong in types, resource lifetimes should be structured, and concurrent work should have ownership.
- [From Go](https://khoralang.com/docs/v0.4/migration/from-go/index.md): Go and Khora agree about the shape of the artifact: one native executable, no VM beside it, fast start, and an operational story you can hold in your head.
- [From Rust](https://khoralang.com/docs/v0.4/migration/from-rust/index.md): Khora shares Rust's goal of native, predictable software without requiring a tracing GC, but it deliberately does not expose Rust's ownership proof system as the ordinary programmer interface.

## Performance

- [Performance](https://khoralang.com/docs/v0.4/performance/index.md): What Khora's HTTP server answers, measured against a generator that is not the bottleneck, and what was wrong with every figure published before it.
- [Making your program faster](https://khoralang.com/docs/v0.4/performance/your-program/index.md): How to find out where a Khora program spends its time, what the toolchain measures for you, and what it does not.

## Limitations

- [Known limitations](https://khoralang.com/docs/v0.4/limitations/index.md): Khora is pre-1.0.

## Optional

- [std::clock](https://khoralang.com/docs/v0.4/stdlib/api/clock/index.md): What time it is, and waiting for it to be later
- [std::config](https://khoralang.com/docs/v0.4/stdlib/api/config/index.md): Settings read out of the environment, through a schema, and reported all at once
- [std::core](https://khoralang.com/docs/v0.4/stdlib/api/core/index.md): The vocabulary every Khora program starts with
- [std::db](https://khoralang.com/docs/v0.4/stdlib/api/db/index.md): Talking to a database, as a capability rather than a library
- [std::decimal](https://khoralang.com/docs/v0.4/stdlib/api/decimal/index.md): Exact decimal arithmetic, for the numbers that are counted rather than measured
- [std::env](https://khoralang.com/docs/v0.4/stdlib/api/env/index.md): What a program was told: its arguments and its environment
- [std::fs](https://khoralang.com/docs/v0.4/stdlib/api/fs/index.md): The file system, over ISO C
- [std::json](https://khoralang.com/docs/v0.4/stdlib/api/json/index.md): JSON, written in Khora
- [std::log](https://khoralang.com/docs/v0.4/stdlib/api/log/index.md): Saying what happened, on the stream meant for it
- [std::net::http](https://khoralang.com/docs/v0.4/stdlib/api/net/http/index.md): HTTP/1.1, over the sockets in std::net::socket
- [std::net::socket](https://khoralang.com/docs/v0.4/stdlib/api/net/socket/index.md): Sockets: listening, connecting, and moving bytes
- [std::net::tls](https://khoralang.com/docs/v0.4/stdlib/api/net/tls/index.md): TLS, over the sockets in std::net::socket
- [std::permissions](https://khoralang.com/docs/v0.4/stdlib/api/permissions/index.md): What the manifest allows, as data the program carries
- [std::permissions::grants](https://khoralang.com/docs/v0.4/stdlib/api/permissions/grants/index.md): What khora.toml granted, as Khora
- [std::process](https://khoralang.com/docs/v0.4/stdlib/api/process/index.md): Running another program
- [std::process::shell](https://khoralang.com/docs/v0.4/stdlib/api/process/shell/index.md): Starting a shell
- [std::random](https://khoralang.com/docs/v0.4/stdlib/api/random/index.md): Numbers nobody chose
- [std::resilience](https://khoralang.com/docs/v0.4/stdlib/api/resilience/index.md): Running something again when the first time did not work
- [std::schema](https://khoralang.com/docs/v0.4/stdlib/api/schema/index.md): One description of a value's shape, used to decode untrusted input
- [std::time](https://khoralang.com/docs/v0.4/stdlib/api/time/index.md): Dates and times as people write them, rather than as a machine counts them
- [std::trace](https://khoralang.com/docs/v0.4/stdlib/api/trace/index.md): Spans, and the context that has to survive a fiber changing worker