kei

Kei

Code is a 契 between humans and AI. コードは人間とAIの契である。

Kei は「AIが書き、人間が承認し、コンパイラが履行を保証する」ことを前提に設計されたプログラミング言語です。人間の書きやすさを捨て、検証可能性・推論の局所性・エージェントループとの親和性に全振りしています。

• ターゲット: TypeScript へトランスパイル(V8 / Cloudflare Workers / Node)
• 実装: Rust の Cargo ワークスペース。ランタイム(@kei/runtime)のみ TypeScript の npm パッケージ
• ツールチェイン: kei CLI と Kei MCP Server を言語仕様と同格の一級市民として扱う

✅ ステータス: v0.1(M0〜M7)+ v0.2(M10〜M13)+ v0.3(M9・M14〜M18)実装完了。 言語処理(パーサ〜トランスパイラ)と MCP サーバーが動作し、kei CLI バイナリ(kei_cli)は check / fmt / build / test が使えます。v0.2 で match 式・extern 署名・契約の検証レベル報告・数量契約イディオム、v0.3 で List<T> コレクション(段階1)・エフェクト事後条件(extern query 観測子)・契約ベース PBT 生成(kei check --generative)・strict-extern・定数恒偽契約の静的検出・Agent Repair Protocol を追加。cargo test --workspace は全件パス。仕様は spec/kei-spec-v0.1.md + spec/kei-spec-v0.2.md + spec/kei-spec-v0.3-collections.md(Draft)が正本です。

🧭 射程(v0.3): 立場B を採択し List を段階導入した。 Kei は「1 エンティティ分の純粋コア DSL」から システム記述言語 へ広がり、List を Result / Option と同格の第三の組み込みジェネリクスとして段階1で導入済み(反復・集計・絞り込みにも uses と契約が効く)。設計は spec/kei-spec-v0.3-collections.md、刻みは v0.3 ロードマップ、親 issue は #25。リテラル構文・量化契約(段階2)は後続。

---

設計思想

原則	中身
合意書原則	シグネチャ + 契約(uses / requires / ensures)だけ読めば、body を読まずに承認判断できる。レビュー単位は実装ではなく契約
曖昧さゼロ	暗黙の型変換なし・暗黙の import なし・演算子オーバーロードなし
推論の局所性	1 ファイルの挙動は、そのファイルと明示 import の宣言だけで決まる。再エクスポート禁止、グローバル可変状態なし
正規形唯一	同じ AST は常に同じテキストに整形される(kei fmt)。スタイル論争は仕様で殺す
エラーは構造化データ	診断は JSON が正、散文は派生。生成→検証→修正ループの帯域を最大化する
null 不在	Option<T> / Result<T, E> のみ。例外機構なし。失敗は型に現れる

コード例

module contracts.withdraw

import core.money { AccountId, Money }
import infra.database as Database

enum WithdrawError {
  NotFound(AccountId)
  Overdraft { limit: Money }
}

func withdraw(account: AccountId, amount: Money) -> Result<Money, WithdrawError>
  uses Database.Read, Database.Write
  requires amount > Money.zero
  ensures result.isOk implies amount > Money.zero
{
  let current = Database.fetchBalance(account) else fail WithdrawError.NotFound(account)
  if current < amount {
    return Err(WithdrawError.Overdraft { limit: current })
  }
  Database.setBalance(account, current - amount)
  return Ok(current - amount)
}

• エフェクトはケーパビリティ: uses に宣言したエフェクトしか行使できない。呼び出し先から推移的に伝播し、未宣言の使用はコンパイルエラー
• 契約: requires / ensures は v0.1 では実行時アサーションに展開される。契約式は副作用禁止(将来の静的証明を壊さないため)
• 失敗の表現: else fail と Result / Option。null も例外もない

ほかのサンプルは examples/(basics / effects / contracts)にあります。

---

リポジトリ構成

6 クレートの Cargo ワークスペース。依存は一方向のみ(逆流・循環禁止):

kei_syntax ←─ kei_fmt
     ↑
kei_check  ←─ kei_emit
     ↑              ↑
     └── kei_cli ──┘
     └── kei_mcp ──┘

クレート	役割	状態
kei_syntax	レキサー + パーサ + AST(型の知識を持たない、エラー回復対応)	✅
kei_check	名前解決・型・エフェクト・契約検査。Diagnostic 型の唯一の定義元	✅
kei_fmt	正規形フォーマッタ(AST の意味的変更禁止)	✅
kei_emit	TS トランスパイラ + source map(検査の再実装禁止)	✅
kei_mcp	MCP サーバー。spec/・examples/ をビルド時埋め込み配信	✅
kei_cli	kei バイナリ。check / fmt / build / test 実装済み	✅

そのほか:

• runtime/ — @kei/runtime(Rust ワークスペース外の独立 npm パッケージ。Result/Option/契約アサーション)
• spec/ — 言語仕様(source of truth)。kei-spec-v0.1.md / diagnostic-schema.md / errors/*.md(エラーコード 1 つにつき 1 ファイル)
• examples/ — .kei サンプル集(kei_examples の配信元、常に check-clean)
• skills/ — Claude Code 向けスキル(kei/SKILL.md。エージェントが Kei を書くための取説、全例 check-clean)
• .claude-plugin/ — プラグイン manifest + marketplace 定義(スキルを配布可能プラグインとして公開)
• tests/ — golden/(契約本文)/ e2e/(トランスパイル→tsc→vitest)/ mcp/(MCP 統合 golden)

詳細は ARCHITECTURE.md を参照(リポジトリ構成の契約)。

---

ビルドとテスト

要件: stable Rust(rust-toolchain.toml で固定、rustfmt + clippy 同梱)。e2e テストのみ Node.js 22 が必要。

# 全テスト(各 Milestone の完了条件)
cargo test --workspace

# 警告ゼロが必須
cargo clippy --workspace --all-targets -- -D warnings

# 整形チェック(CI の fmt ジョブと同じ)
cargo fmt --all -- --check

# ランタイム(TypeScript)をビルド
cd runtime && npm install && npm run build

CI(.github/workflows/ci.yml)は fmt / clippy / test の 3 ジョブ。test ジョブは Node 22 をセットアップする(e2e が npm/npx を使うため)。

テスト規模(現状): golden — syntax 23 / check 41 / fmt 10 ペア、MCP 18 ペア。e2e vitest 10 本。エラーコード解説 34 本。

---

kei CLI

ツールチェインのコマンドラインフロントエンド。check / fmt / build / test の 4 サブコマンドを提供します。

# 1. ビルド済みバイナリ(Rust 不要・macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/A-1ro/kei-lang/main/install.sh | sh