Kiroha

Documentation (GitHub Pages): kiroha-lang.github.io/kiroha

Claude Code plugin: claude plugin marketplace add kiroha-lang/kiroha, then claude plugin install kiroha@kiroha-lang. Guide.

Kiroha 0.8.0 replaces the earlier check function with .as[...] and .as(schema). See the 0.8 migration guide.

Kiroha (きろは) combines the original working name Kiri with iroha, the basics of a language. The executable and source extension are kiroha and .kiroha. See the naming and migration note.

Kiroha is a small, strict, immutable expression language for programs that manipulate JSON, call web services, serve HTTP APIs and use PostgreSQL, MySQL or MariaDB. It was designed to be written by LLMs: the standard surface is 30 global functions, 19 collection methods and one .size property, numbers are exact decimals, every effect is explicit and capability-checked, and there is exactly one way to pass a callback — a mandatory trailing lambda.

type User = open({id:int, name:str, active:bool});

get("https://api.example/users").as[[User]]
  .filter{u => u.active}
  .map{u => {id:u.id, name:u.name}}

This repository is a complete Rust implementation of the Kiroha 0.8.0 / Web1 specification (spec.md), including the kiroha command-line tool, a deterministic conformance runner and production adapters for HTTP/1.1 (+ verified TLS), PostgreSQL 16, MySQL 8.4, MariaDB 11.4, an HTTP server and the local filesystem.

Status

Area	State
Embedded conformance corpus (spec §16)	263 / 263 pass, including explicit types, generics, compact definitions and receiver members (kiroha conformance spec.md --json)
Integration scenarios I01–I08 (spec §15.3)	All pass (PostgreSQL 16.4; additional backend tests use MySQL 8.4.4 / MariaDB 11.4.5)
Extra prose-rule regressions	Pass (tests/prose_regressions.rs)
Formal verification	TLA+ models of parallel and tx model-checked with TLC; property-based tests of decimals and JSON against oracles (details)
30 globals + 19 methods + size + 5 schema atoms	Implemented; inventory matches the generation card
CLI protocol kiroha-cli/1	Implemented
Acceptance	Release CI exercises PostgreSQL/MySQL/MariaDB and syntax regressions; the dated 0.3 baseline passed audit 23 (record)

Details, versions and known deviations are in docs/conformance-report.md.

Install

curl -fsSL https://github.com/kiroha-lang/kiroha/releases/latest/download/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
kiroha --version

Prebuilt releases support Linux/WSL (glibc 2.35+) and macOS 13+, on x86_64 and ARM64. No Rust build environment is needed. The installer verifies SHA-256 and defaults to ~/.local/bin; see installation options for version pinning, alternate directories and source builds.

Build from source

Requires Rust 1.89+ (tested with 1.96), a C compiler and libclang (for the embedded PostgreSQL parser, pg_query; set LIBCLANG_PATH if it is not found automatically).

cargo build --release
cp target/release/kiroha ~/.local/bin/     # or anywhere on PATH
kiroha --version

Codex plugin

Give an agent Kiroha's versioned generation card, API guidance and runnable examples:

codex plugin marketplace add kiroha-lang/kiroha
codex plugin add kiroha@kiroha-lang

Use $kiroha:write-kiroha to write, review, debug or migrate Kiroha programs. See the plugin guide for usage, local development and packaging.

Quick start

echo 'fun fac(n:int):int if n<=1 then 1 else n*fac(n-1) end fun fac fac(20)' > fac.kiroha
kiroha check fac.kiroha --json      # lex, parse, resolve and type-check
kiroha run fac.kiroha --json        # evaluate
# {"protocol":"kiroha-cli/1","ok":true,"result":{"t":"number","v":"2432902008176640000"}}

By default a program may compute and sleep but every external capability (network, files, environment, clock, randomness, logging, database, listening) is denied. Grant capabilities with a host file:

{
  "format": "kiroha-host/1",
  "capabilities": {
    "http": ["https://api.example"],
    "log": true
  }
}

kiroha run program.kiroha --json --host host.json

See the examples and their setup instructions for runnable programs.

Documentation

Document	Contents
Language guide	Tutorial: syntax, callbacks, scope, pipes, errors, schemas, concurrency, HTTP, SQL, servers
Types and generics	Local inference, annotations, explicit any, structural types and simple generics
Database guide	Shared API, backend configuration and SQL/type differences
0.6 migration	Type declarations and checked function signatures
0.5 migration	Compact definitions, collection methods and .size
0.4 migration	fun name(...) ... end fun name, body sequences and reserved words
0.8 migration	Replace check with .as, and use SQL blocks
Built-in reference	All globals, collection members and 5 schema atoms: signatures, defaults, validation, errors
Values and numbers	Value kinds, exact decimals, canonical spelling, JSON, equality
Errors and aborts

Development

cargo test                                  # unit + integration tests
KIROHA_TEST_PG_DSN="host=127.0.0.1 port=55432 user=kiroha dbname=postgres" cargo test   # include PostgreSQL I03/I04
cargo run --release -- conformance spec.md --json
./formal/check.sh                           # TLA+ model checking (needs Java)
python scripts/measure.py --check            # requires tiktoken==0.14.0

Without KIROHA_TEST_PG_DSN the PostgreSQL tests print SKIP and pass vacuously; the conformance report states which environment was used.

MySQL and MariaDB use the same database abstraction (backend in a host database_pools entry: postgresql (default), mysql or mariadb). Their real-server tests in tests/database_backends.rs are enabled by DSNs and skip without them:

KIROHA_TEST_MYSQL_DSN='mysql://user:[email protected]:3306/db' \
KIROHA_TEST_MARIADB_DSN='mariadb://user:[email protected]:3307/db' cargo test --test database_backends

The verification workflow provisions PostgreSQL 16 and runs the build, tests, conformance corpus, warning-free Clippy, TLC models and measurement check. Regenerate measurements after editing spec.md with python scripts/measure.py.