Overview
How an AI agent is expected to work with Sakura Lang, from reading the docs to handing signature changes to a human.
Pre-alpha
The source-built compiler runs the core language and much of M3 on JavaScript: contracts, typed effects and failures, std handlers, permissions, LSP and MCP. M3 is still in progress; no release or stable compatibility contract exists. See the roadmap for implemented features and remaining gates.
Sakura Lang is designed to be written by agents and reviewed by humans. The signature is the contract: parameter types with refinements, result type, effect row, error union, and requires/ensures. Agents write bodies against it; humans review signatures and the diff of signatures.
Available today
| Resource | What it is |
|---|---|
/llms.txt | Index of every page on this site, with titles, descriptions, and URLs. |
/llms-full.txt | Every page on this site concatenated into one Markdown file. |
/docs/<page>.md | Any page on this site as Markdown. Append .md to its URL; the docs root is /docs.md. |
| Copy as Markdown | A button at the top of every page, next to a menu with the .md link and the GitHub source. |
docs/llms.txt | The language reference for agents: the whole core language in one file of about 4,500 tokens. Lives in the repository. |
docs/design.md | The authoritative v0 design. When anything else disagrees with it, it wins. |
The two llms.txt files are different things. See llms.txt.
Toolchain by milestone
| Tool | Purpose | Design |
|---|---|---|
sakura check --json | Diagnostics, holes, and obligations as JSON Lines. | design §12.2, M0 |
?name typed holes | Placeholders the checker reports with expected type, effects, locals, and candidates. | design §12.4, M2 |
sakura prompt | Emits docs/llms.txt matched to the compiler's edition, plus requested library signatures. | design §12.1, M2 |
sakura fix, --frozen-specs | Applies compiler fixes by impact class and rejects patches that touch frozen specs. | design §7.3, M3 |
sakura audit, sakura doc | Trust inventory and offline signature search. | design §17.78, M3 |
sakura build --manifest | Trusted components and runtime contract obligations. | design §17.76, M3 |
sakura test --record | Opt-in cassette recording; ordinary tests replay offline. | design §17.73, M3 |
sakura mcp serve | The compiler as Model Context Protocol tools. | design §12.6, M3 |
Milestones are defined in design §14.3. See also the roadmap.
The intended loop
This is how an agent is expected to work with the full v0 toolchain. sakura fix, --frozen-specs, and the compiler MCP server are available.
Load the language
Read docs/llms.txt once per session (or run sakura prompt). It is the entire core language. Look up library signatures with the MCP symbol_query tool instead of guessing; sakura doc --search is also available offline.
Write signatures first, bodies as holes
fn clamp(x: Int, lo: Int, hi: Int) -> Int
requires ordered: lo <= hi
ensures bounded: lo <= result && result <= hi
{
?body
}sakura check accepts holes. Signatures are what a human reviews, so get them right first.
Check
Run sakura check --json, or call the MCP check tool. Each typed hole comes back as a hole record with its expected type, allowed effects, locals, and ranked candidates.
Fill holes and fix diagnostics
Each problem is a diagnostic record with a stable code, byte spans, structured expected/actual, and fixes. See Diagnostics. sakura explain V3001 gives the rationale for a code.
Apply fixes by impact class
local fixes that are machine_applicable are safe to apply. interface_change, contract_change, and authority_change fixes are never machine_applicable; sakura fix never applies the last two. Run sakura test --json, then sakura fmt.
Report signature changes
If the task really needs a new effect, error tag, permission, or a changed contract, make the change and list it for the reviewer. During repair, specs can be frozen (--frozen-specs), and any patch that touches them is rejected with V8020.
What an agent should never do
- Add an effect, error tag, or
[permissions]entry without flagging it. - Weaken or delete a
requires,ensures, orwhereclause, or edit atestbody, to make a check pass. Contract violations (D020,D021) mean the caller or callee is wrong, not the spec. - Use
.trust(@trust("...")),Secret.expose,.expect, orEmail.fromoutside trusted boundaries, or without a true reason. - Leave a
?holein code meant to build.sakura buildandsakura runreject it withV2050. - Borrow syntax from other languages: call-site type arguments (
f<T>(x),V0011) and named arguments (f(name: v),V0014) do not exist. Annotate the binding (let rows: List<User> = Sql.query(q)) and pass a record for options. Import every non-prelude name explicitly (import std/http.{Http}andimport std/request.{Request}).
Pages in this section
llms.txt
The site's Markdown exports and the language's docs/llms.txt.
MCP server
The implemented sakura mcp serve compiler tools and @tool export.
Diagnostics
The JSON Lines format, error codes, and fix impact classes.
Typed holes
Writing programs incrementally with ?name.
Trust audit
Inventory explicit trust, totality and refinement boundaries.
Offline API search
Query signatures, effect rows and contracts with sakura doc.
Build manifest
Inspect trusted dependencies and runtime contract obligations.
Cassettes and recording
Replay HTTP and LLM exchanges offline; opt into recording.
Concurrency
Structured concurrency with the Task effect, cooperative cancellation, timeouts, retries, budgets, and deterministic scheduling in Sakura Lang.
llms.txt and Markdown exports
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.