# Sakura Lang

> Sakura Lang is an agent-first programming language. Every signature declares its effects, errors and contracts, and the compiler seals them on every build.

Sakura Lang is pre-alpha and nothing is released. The v0 language design is written (docs/design.md in the repository). The compiler builds from source and checks and runs M0 to M2 programs (effects, handlers, typed errors, holes) on JavaScript; the M3 standard library (http, sql, fs, cli, ai, task) is not built yet, so examples that use it do not run. Build it: https://sakura-lang.vercel.app/docs/quickstart

- The core language for agents, in one file: https://github.com/icantcodefyi/sakura-lang/blob/master/docs/llms.txt
- Every docs page is available as Markdown: append `.md` to its URL (for example https://sakura-lang.vercel.app/docs/tour/effects.md).
- All docs in one file: https://sakura-lang.vercel.app/llms-full.txt

## Start
- [Introduction](https://sakura-lang.vercel.app/docs): Sakura Lang is an agent-first, general-purpose programming language in which the signature is the contract.
- [Why Sakura Lang](https://sakura-lang.vercel.app/docs/why-sakura-lang): The problem with reviewing agent-written code, the thesis that the signature should be the contract, and the principles that follow from it.
- [Quickstart](https://sakura-lang.vercel.app/docs/quickstart): Build the Sakura Lang compiler from source, then check, test and run a first program.

## Language Tour
- [Basics](https://sakura-lang.vercel.app/docs/tour/basics): Lexical rules, bindings, functions, control flow, operators, strings, lambdas, loops, and modules in Sakura Lang.
- [Types](https://sakura-lang.vercel.app/docs/tour/types): Primitive types, records, variants, refinements, generics with derived constraints, inference, method-call resolution, and exhaustive pattern matching in Sakura Lang.
- [Effects](https://sakura-lang.vercel.app/docs/tour/effects): How Sakura Lang records every side effect and every expected failure in the function signature, and how effect rows compose.
- [Handlers](https://sakura-lang.vercel.app/docs/tour/handlers): How handlers give effects their meaning, how to install them with `with`, handler state, and how tests swap handlers.
- [Contracts and refinements](https://sakura-lang.vercel.app/docs/tour/contracts): Refinement types, requires and ensures clauses, and the honest guarantee model behind them.
- [Testing](https://sakura-lang.vercel.app/docs/tour/testing): Unit tests, property tests, contract-generated tests, snapshots, and deterministic handlers in Sakura Lang.
- [Capabilities and security](https://sakura-lang.vercel.app/docs/tour/capabilities): How Sakura Lang separates effects from authority, limits root handlers with sakura.toml, narrows authority for dependencies, and blocks injection and secret leaks.
- [Memory model](https://sakura-lang.vercel.app/docs/tour/memory): Value semantics, var rebinding, compiler-inserted reference counting with Perceus reuse, cycles through Graph, scope-bound resources, and backends in Sakura Lang.
- [Concurrency](https://sakura-lang.vercel.app/docs/tour/concurrency): Structured concurrency with the Task effect, cooperative cancellation, timeouts, retries, budgets, and deterministic scheduling in Sakura Lang.

## For Agents
- [Overview](https://sakura-lang.vercel.app/docs/agents): How an AI agent is expected to work with Sakura Lang, from reading the docs to handing signature changes to a human.
- [llms.txt and Markdown exports](https://sakura-lang.vercel.app/docs/agents/llms-txt): The two llms.txt files for Sakura Lang - this site's Markdown exports, and the language reference in docs/llms.txt that sakura prompt will emit.
- [MCP server](https://sakura-lang.vercel.app/docs/agents/mcp): The sakura mcp serve server, which exposes the compiler to agents as Model Context Protocol tools, and @tool export of your own functions.
- [Diagnostics](https://sakura-lang.vercel.app/docs/agents/diagnostics): Reference for the JSON Lines diagnostics produced by sakura check --json, including record kinds, error codes, and fix impact classes.
- [Typed holes](https://sakura-lang.vercel.app/docs/agents/typed-holes): How ?name holes let agents write a Sakura Lang program incrementally, with the checker reporting what fits in each gap.
- [Trust audit](https://sakura-lang.vercel.app/docs/agents/audit): Inventory trust assumptions and explicit refinement conversions with sakura audit.
- [Offline API search](https://sakura-lang.vercel.app/docs/agents/doc): Find signatures, effects, contracts and documentation with sakura doc.
- [Build manifest](https://sakura-lang.vercel.app/docs/agents/build-manifest): Inspect the trusted base and runtime contract obligations emitted by sakura build --manifest.
- [Offline cassettes and recording](https://sakura-lang.vercel.app/docs/agents/cassettes): Replay HTTP and LLM exchanges with Test.fixtures, and opt into recording with --record.

## Reference
- [Standard library](https://sakura-lang.vercel.app/docs/stdlib): Public std signatures generated from compiler/std/INDEX.md, with current JS limitations.
- [Roadmap](https://sakura-lang.vercel.app/docs/roadmap): Finish M3, establish WASM and verification in M4, then add native code and Perceus in M5.
- [Prior art](https://sakura-lang.vercel.app/docs/prior-art): What Sakura Lang takes from Koka, Effect-TS, Rust, Lean, Dafny, Elm, Gleam and others, what it rejects, and why.
- [FAQ](https://sakura-lang.vercel.app/docs/faq): Honest answers to common questions about Sakura Lang's status, design choices, and relationship to other languages.