Edict Lang

Edict

AI エージェント向けに設計されたプログラミング言語です。 パーサーも構文もありません。エージェントは AST を JSON として直接生成します。

Edict は、正規のプログラム形式として JSON AST を採用した、静的型付けとエフェクト追跡を備えるプログラミング言語です。AI エージェントが、構造化されたパイプラインを通じてプログラムを作成、検証、実行できるように専用設計されています。テキストの解析も、人間が読める構文も、曖昧さもありません。

Agent (LLM)
  │  produces JSON AST via MCP tool call
  ↓
Schema Validator ─── invalid? → StructuredError → Agent retries
  ↓
Name Resolver ────── undefined? → StructuredError + candidates → Agent retries
  ↓
Type Checker ─────── mismatch? → StructuredError + expected type → Agent retries
  ↓
Effect Checker ───── violation? → StructuredError + propagation chain → Agent retries
  ↓
Contract Verifier ── unproven? → StructuredError + counterexample → Agent retries
  (Z3/SMT)            ↓
                  Code Generator (pure-JS WASM encoder) → WASM → Execute

特長

• JSON AST — プログラムはテキストファイルではなく、JSON オブジェクトです。字句解析器もパーサーもありません。
• 構造化されたエラー — すべてのエラーは、エージェントが自力で修正できるだけのコンテキストを含む、型付き JSON オブジェクトです。
• 型システム — Int、Float、String、Bool、Array<T>、Option<T>、Result<T,E>、レコード、列挙型、精緻化型に対応しています。
• エフェクト追跡 — 関数は pure、reads、writes、io、fails を宣言します。コンパイラーが整合性を検証します。
• コントラクト検証 — 事前条件と事後条件は、Z3（SMT 経由）によってコンパイル時に検証されます。コントラクトに違反すると、具体的な反例が返されます。
• WASM コンパイル — 検証済みのプログラムは、純粋な JavaScript エンコーダーによって WebAssembly にコンパイルされ、Node.js で実行されます。
• MCP インターフェース — すべてのツールが Model Context Protocol 経由で公開され、エージェントと直接連携できます。
• スキーマ移行 — 古いスキーマバージョンの AST は自動的に移行されます。言語が進化しても互換性が損なわれません。

実行モデル

Edict は WebAssembly にコンパイルされ、サンドボックス化された VM で実行されます。これは制約ではなく、意図的なセキュリティ上の判断です。

• 暗黙の権限なし — コンパイル済みの WASM は、ホストがプラグイン可能な EdictHostAdapter インターフェースを通じて明示的に機能を提供しない限り、ファイルシステム、ネットワーク、OS にアクセスできません
• コンパイル時の機能宣言 — エフェクトシステム（io、reads、writes、fails）により、ホストはプログラムの実行前に必要な機能を確認できます
• 実行時の強制 — RunLimits によって、実行タイムアウト、メモリ上限、ファイルシステムのサンドボックス化を制御します
• 多層防御 — すぐに実行されるエージェント生成コードには、人間がレビューしたコードよりも強固な隔離が必要です。エフェクトシステム、WASM サンドボックス、ホストアダプターパターンの組み合わせが、まさにそれを実現します

アダプターを通じて利用できるホスト機能：ファイルシステム（サンドボックス化）、HTTP、暗号処理（SHA-256、MD5、HMAC）、環境変数、CLI 引数。新しい機能は EdictHostAdapter を拡張して追加できます。

クイックスタート

AI エージェント向け（MCP）

Edict を最も手軽に利用する方法は、MCP サーバーを使うことです。コンパイラーパイプライン全体をツール呼び出しとして公開します。

npx edict-lang          # start MCP server (stdio transport, no install needed)

または、ローカルにインストールします。

npm install edict-lang
npx edict-lang          # start MCP server

開始に必要な呼び出しは 2 回です：edict_schema（AST 形式を確認）→ edict_check（プログラムを送信）。すべてのツールについては、MCP ツールを参照してください。

開発向け

npm install
npm test          # 2675 tests across 136 files
npm run mcp       # start MCP server (stdio transport)

Docker

ローカルに Node.js をインストールせずに、Edict MCP サーバーをコンテナーで実行できます。

# stdio transport (default — for local MCP clients)
docker run -i ghcr.io/sowiedu/edict

# HTTP transport (for remote/networked MCP clients)
docker run -p 3000:3000 -e EDICT_TRANSPORT=http ghcr.io/sowiedu/edict

対応プラットフォーム：linux/amd64、linux/arm64。

ブラウザー

Edict コンパイラーをブラウザー内で完全に実行できます。サーバーは不要です。

バンドル	サイズ	フェーズ	用途
edict-lang/browser	318 KB	1–3（検証、解決、型チェック、エフェクト、リント、パッチ）	軽量なチェック
edict-lang/browser-full	~14 MB	1–5（+ WASM コード生成、Z3 コントラクト、WASM 実行）	完全なコンパイルと実行

import { compileBrowser, runBrowserDirect } from 'edict-lang/browser-full';

const result = compileBrowser(astJson);
if (result.ok) {
    const run = await runBrowserDirect(result.wasm);
    console.log(run.output);  // "Hello, World!"
}

注：ESM モジュールの実行には HTTP による配信が必要です。npx serve . または任意の静的サーバーを使用してください。file:// では動作しません。

動作するサンプルについては、examples/browser/index.html を参照してください。

QuickJS（サンドボックス環境）

Edict コンパイラーは QuickJS WASM 内でも実行できます。サンドボックス化されたランタイム、エッジワーカー、または他の WASM アプリケーションへの組み込みに便利です。

バンドル	サイズ	フェーズ	Node.js と比べた速度低下
dist/edict-quickjs-check.js	373 KB	1–3（検証、解決、型チェック、エフェクト）	~3.7x
dist/edict-quickjs-full.js	932 KB	1–5（チェック + WASM コンパイル）	~3.7x

import { EdictQuickJS } from "edict-lang/quickjs";

const edict = await EdictQuickJS.createFull();  // phases 1-5
const result = edict.compile(ast);
if (result.ok) {
    console.log(result.wasm);  // Uint8Array of valid WASM
}
edict.dispose();

注：quickjs-emscripten はオプションのピア依存関係です。EdictQuickJS を使用するには、edict-lang と一緒にインストールしてください。fs を利用できない環境では、ディスクから読み込む代わりに bundleSource を直接渡してください。

ベンチマークと推奨事項の詳細については、docs/quickjs-feasibility-report.md を参照してください。

MCP ツール

ツール	説明
edict_schema	完全な AST JSON Schema を返します。プログラムの記述方法を定める仕様です
edict_version	コンパイラーのバージョンと機能情報を返します
edict_examples	41 個のサンプルプログラムを JSON AST として返します（スキーマの抜粋を含みます）
edict_validate	AST の構造（フィールド名、型、ノードの種類）を検証します
edict_check	完全なパイプライン：検証 → 名前の解決 → 型チェック → エフェクトチェック → コントラクトの検証
edict_compile	チェック済みの AST を WASM にコンパイルします（base64 エンコードされたバイナリを返します）
edict_run	コンパイル済み WASM バイナリを実行し、出力と終了コードを返します
edict_patch	nodeId を指定して対象の AST パッチを適用し、再チェックします
edict_errors	すべてのエラー種別の機械可読な一覧を返します
edict_lint	処理をブロックしない品質分析を実行し、警告を返します
edict_debug	実行トレースとクラッシュ診断を行います
edict_compose	合成可能なプログラムの断片を組み合わせてモジュールを作成します
edict_explain	AST ノード、エラー、またはコンパイラーの動作を説明します
edict_export	プログラムを UASF ポータブルスキルとしてパッケージ化します
edict_import_skill	UASF スキルパッケージをインポートして実行します
edict_generate_tests	Z3 で検証されたコントラクトからテストを生成します
edict_replay	決定的な実行トレースを記録して再生します
edict_deploy	Edict プログラムをコンパイルし、エッジランタイム（Cloudflare Workers）にデプロイします
edict_invoke	HTTP 経由でデプロイ済みの Edict WASM サービスを呼び出します
edict_invoke_skill	UASF スキルパッケージを直接呼び出します
edict_package	コンパイル済みプログラムを、デプロイ可能なスキルバンドルとしてパッケージ化します
edict_support	トラブルシューティング用の診断情報と環境情報を返します

MCP リソース

URI	説明
edict://schema	完全な AST JSON Schema
edict://schema/minimal	トークン効率の高いブートストラップ用の最小スキーマバリアント
edict://examples	すべてのサンプルプログラム
edict://errors	機械可読なエラー一覧
edict://schema/patch	AST パッチプロトコルの JSON Schema
edict://guide	MCP ファーストの導入向けエージェントブートストラップガイド
edict://support	診断情報と環境情報

サンプルプログラム

Edict の JSON AST で記述した「Hello, World!」：

{
  "kind": "module",
  "id": "mod-hello-001",
  "name": "hello",
  "imports": [],
  "definitions": [
    {
      "kind": "fn",
      "id": "fn-main-001",
      "name": "main",
      "params": [],
      "effects": ["io"],
      "returnType": { "kind": "basic", "name": "Int" },
      "contracts": [],
      "body": [
        {
          "kind": "call",
          "id": "call-print-001",
          "fn": { "kind": "ident", "id": "ident-print-001", "name": "print" },
          "args": [
            { "kind": "literal", "id": "lit-msg-001", "value": "Hello, World!" }
          ]
        },
        { "kind": "literal", "id": "lit-ret-001", "value": 0 }
      ]
    }
  ]
}

エージェントループ

基本設計は、エージェントが AST を送信し、コンパイラーが検証するというものです。誤りがある場合、コンパイラーはエージェントが自ら修正できるだけのコンテキストを含む StructuredError を返します。エージェントはそれを修正し、再送信します。

// 1. Agent reads the schema to learn the AST format
const schema = edict_schema();

// 2. Agent writes a program (may contain errors)
const program = agentWritesProgram(schema);

// 3. Compile — returns structured errors or WASM
const result = edict_compile(program);

if (!result.ok) {
  // 4. Agent reads errors and fixes the program
  //    Errors include: nodeId, expected type, candidates, counterexamples
  const fixed = agentFixesProgram(program, result.errors);
  // 5. Resubmit
  return edict_compile(fixed);
}

// 6. Run the WASM
const output = edict_run(result.wasm);

アーキテクチャ

src/
├── ast/           # TypeScript interfaces for every AST node
├── validator/     # Schema validation (structural correctness)
├── resolver/      # Name resolution (scope-aware, with Levenshtein suggestions)
├── checker/       # Type checking (bidirectional, with unit types)
├── effects/       # Effect checking (call-graph propagation)
├── contracts/     # Contract verification (Z3/SMT integration)
├── codegen/       # WASM code generation (pure-JS encoder)
│   ├── codegen.ts       # IR → WASM module orchestration
│   ├── compile-ir-expr.ts  # IR expression compilation
│   ├── compile-ir-*.ts  # Specialized IR compilers (calls, data, match, scalars)
│   ├── runner.ts        # WASM execution (Node.js WebAssembly API)
│   ├── host-adapter.ts  # EdictHostAdapter interface + platform adapters
│   ├── closures.ts      # Closure capture and compilation
│   ├── hof-generators.ts # Higher-order function WASM generators
│   ├── wasm-encoder.ts  # Pure-JS WASM binary encoder (replaced binaryen)
│   ├── wasm-interpreter.ts # Pure-JS WASM interpreter (no WebAssembly API needed)
│   ├── recording-adapter.ts # Execution recording for replay
│   ├── replay-adapter.ts  # Deterministic replay from recorded traces
│   └── string-table.ts  # String interning for WASM memory
├── ir/            # Mid-level IR (lowering, optimization)
├── builtins/      # Builtin registry and domain-specific builtins
├── compact/       # Compact AST format (token-efficient for agents)
├── compose/       # Composable program fragments
├── deploy/        # Edge deployment scaffolding (Cloudflare Workers)
├── incremental/   # Incremental checking (dependency graph + diff)
├── lint/          # Non-blocking quality warnings
├── patch/         # Surgical AST patching by nodeId
├── migration/     # Schema version migration (auto-upgrade older ASTs)
├── skills/        # Skill packaging and invocation
├── mcp/           # MCP server (tools + resources + prompts)
└── errors/        # Structured error types

tests/             # 2675 tests across 136 files
examples/          # 41 example programs (⭐→⭐⭐⭐ difficulty in README)
schema/            # Auto-generated JSON Schema

型システム

型	例
基本型	Int, Int64, Float, String, Bool
配列	Array<Int>
オプション	Option<String>
結果	Result<String, String>
レコード	Point { x: Float, y: Float }
列挙型	Shape = Circle { radius: Float } | Rectangle { w: Float, h: Float }
精緻化型	{ i: Int | i > 0 } — Z3 によって検証される述語
関数	(Int, Int) -> Int

エフェクトシステム

関数ではエフェクトを宣言します。コンパイラーは次の内容を強制します。

• pure 関数は io 関数を呼び出せません
• エフェクトは呼び出しグラフを通じて伝播します
• 不足しているエフェクトは検出され、報告されます

エフェクト：pure、reads、writes、io、fails

コントラクト検証

事前条件と事後条件は、Z3 を使用してコンパイル時に検証されます。

{
  "kind": "post",
  "id": "post-001",
  "condition": {
    "kind": "binop", "id": "binop-001", "op": ">",
    "left": { "kind": "ident", "id": "ident-result-001", "name": "result" },
    "right": { "kind": "ident", "id": "ident-x-001", "name": "x" }
  }
}

Z3 は unsat（コントラクトが成立 ✅）を証明するか、エージェントが推論に利用できる具体的な反例とともに sat を返します。

貢献

エージェントと人間の皆さまからの貢献を歓迎します。セットアップ手順、コーディング規約、PR のワークフローについては、CONTRIBUTING.md をご覧ください。

最初に取り組む課題をお探しですか？ good first issue ラベルが付いた issue をご確認ください。

ロードマップ

開発計画の全容は ROADMAP.md、言語仕様は FEATURE_SPEC.md、エージェントが検証済みの WASM スキルを保存して再利用する方法は Crystallized Intelligence をご覧ください。

サポート

Edict は MIT ライセンスのもとで提供される、無料のオープンソースソフトウェアです。エージェントにとって役立つと感じた場合は、開発へのスポンサーをご検討ください。

ライセンス

MIT