{
"markdown": "# Edict\n\n[](https://github.com/Sowiedu/Edict/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://nodejs.org)\n[](https://modelcontextprotocol.io/)\n\n![](\"https://glama.ai/mcp/servers/Sowiedu/Edict/badge\")
\n\n**A programming language designed for AI agents.** No parser. No syntax. Agents produce AST directly as JSON.\n\nEdict is a statically-typed, effect-tracked programming language where the canonical program format is a JSON AST. It's purpose-built so AI agents can write, verify, and execute programs through a structured pipeline — no text parsing, no human-readable syntax, no ambiguity.\n\n```\nAgent (LLM)\n │ produces JSON AST via MCP tool call\n ↓\nSchema Validator ─── invalid? → StructuredError → Agent retries\n ↓\nName Resolver ────── undefined? → StructuredError + candidates → Agent retries\n ↓\nType Checker ─────── mismatch? → StructuredError + expected type → Agent retries\n ↓\nEffect Checker ───── violation? → StructuredError + propagation chain → Agent retries\n ↓\nContract Verifier ── unproven? → StructuredError + counterexample → Agent retries\n (Z3/SMT) ↓\n Code Generator (pure-JS WASM encoder) → WASM → Execute\n```\n\n## Features\n\n- **JSON AST** — Programs are JSON objects, not text files. No lexer, no parser.\n- **Structured errors** — Every error is a typed JSON object with enough context for an agent to self-repair.\n- **Type system** — `Int`, `Float`, `String`, `Bool`, `Array`, `Option`, `Result`, records, enums, refinement types.\n- **Effect tracking** — Functions declare `pure`, `reads`, `writes`, `io`, `fails`. The compiler verifies consistency.\n- **Contract verification** — Pre/post conditions verified at compile time by Z3 (via SMT). Failing contracts return concrete counterexamples.\n- **WASM compilation** — Verified programs compile to WebAssembly via a pure-JS encoder and run in Node.js.\n- **MCP interface** — All tools exposed via [Model Context Protocol](https://modelcontextprotocol.io/) for direct agent integration.\n- **Schema migration** — ASTs from older schema versions are auto-migrated. No breakage when the language evolves.\n\n## Execution Model\n\nEdict compiles to **WebAssembly** and runs in a sandboxed VM. This is a deliberate security decision — not a limitation:\n\n- **No ambient authority** — compiled WASM cannot access the filesystem, network, or OS unless the host explicitly provides those capabilities via the pluggable `EdictHostAdapter` interface\n- **Compile-time capability declaration** — the effect system (`io`, `reads`, `writes`, `fails`) lets the host inspect what a program requires _before_ running it\n- **Runtime enforcement** — `RunLimits` controls execution timeout, memory ceiling, and filesystem sandboxing\n- **Defense-in-depth** — agent-generated code that runs immediately needs stronger isolation than human-reviewed code. The effect system + WASM sandbox + host adapter pattern provides exactly that\n\nHost capabilities available through adapters: filesystem (sandboxed), HTTP, crypto (SHA-256, MD5, HMAC), environment variables, CLI arguments. New capabilities are added by extending `EdictHostAdapter`.\n\n## Quick Start\n\n### For AI Agents (MCP)\n\nThe fastest way to use Edict is through the **MCP server** — it exposes the entire compiler pipeline as tool calls:\n\n```bash\nnpx edict-lang # start MCP server (stdio transport, no install needed)\n```\n\nOr install locally:\n\n```bash\nnpm install edict-lang\nnpx edict-lang # start MCP server\n```\n\n**Two calls to get started**: `edict_schema` (learn the AST format) → `edict_check` (submit a program). See [MCP Tools](#mcp-tools) for the full tool list.\n\n### For Development\n\n```bash\nnpm install\nnpm test # 2675 tests across 136 files\nnpm run mcp # start MCP server (stdio transport)\n```\n\n## Docker\n\nRun the Edict MCP server in a container — no local Node.js required:\n\n```bash\n# stdio transport (default — for local MCP clients)\ndocker run -i ghcr.io/sowiedu/edict\n\n# HTTP transport (for remote/networked MCP clients)\ndocker run -p 3000:3000 -e EDICT_TRANSPORT=http ghcr.io/sowiedu/edict\n```\n\nSupported platforms: `linux/amd64`, `linux/arm64`.\n\n## Browser\n\nRun the Edict compiler entirely in the browser — no server required:\n\n| Bundle | Size | Phases | Use case |\n|---|---|---|---|\n| `edict-lang/browser` | 318 KB | 1–3 (validate, resolve, typecheck, effects, lint, patch) | Lightweight checking |\n| `edict-lang/browser-full` | ~14 MB | 1–5 (+ WASM codegen, Z3 contracts, WASM execution) | Full compile & run |\n\n```javascript\nimport { compileBrowser, runBrowserDirect } from 'edict-lang/browser-full';\n\nconst result = compileBrowser(astJson);\nif (result.ok) {\n const run = await runBrowserDirect(result.wasm);\n console.log(run.output); // \"Hello, World!\"\n}\n```\n\n> **Note**: ESM modules require HTTP serving. Use `npx serve .` or any static server — `file://` won't work.\n\nSee [`examples/browser/index.html`](examples/browser/index.html) for a working example.\n\n## QuickJS (Sandboxed Environments)\n\nThe Edict compiler also runs inside [QuickJS](https://bellard.org/quickjs/) WASM — useful for sandboxed runtimes, edge workers, or embedding in other WASM applications:\n\n| Bundle | Size | Phases | Slowdown vs Node.js |\n|---|---|---|---|\n| `dist/edict-quickjs-check.js` | 373 KB | 1–3 (validate, resolve, typecheck, effects) | ~3.7x |\n| `dist/edict-quickjs-full.js` | 932 KB | 1–5 (check + WASM compile) | ~3.7x |\n\n```typescript\nimport { EdictQuickJS } from \"edict-lang/quickjs\";\n\nconst edict = await EdictQuickJS.createFull(); // phases 1-5\nconst result = edict.compile(ast);\nif (result.ok) {\n console.log(result.wasm); // Uint8Array of valid WASM\n}\nedict.dispose();\n```\n\n> **Note**: `quickjs-emscripten` is an optional peer dependency — install it alongside `edict-lang` to use `EdictQuickJS`. For fs-free environments, pass `bundleSource` directly instead of loading from disk.\n\nSee [docs/quickjs-feasibility-report.md](docs/quickjs-feasibility-report.md) for full benchmarks and recommendations.\n\n## MCP Tools\n\n| Tool | Description |\n|---|---|\n| `edict_schema` | Returns the full AST JSON Schema — the spec for how to write programs |\n| `edict_version` | Returns compiler version and capability info |\n| `edict_examples` | Returns 41 example programs as JSON ASTs (includes schema snippet) |\n| `edict_validate` | Validates AST structure (field names, types, node kinds) |\n| `edict_check` | Full pipeline: validate → resolve names → type check → effect check → verify contracts |\n| `edict_compile` | Compiles a checked AST to WASM (returns base64-encoded binary) |\n| `edict_run` | Executes a compiled WASM binary, returns output and exit code |\n| `edict_patch` | Applies targeted AST patches by nodeId and re-checks |\n| `edict_errors` | Returns machine-readable catalog of all error types |\n| `edict_lint` | Runs non-blocking quality analysis and returns warnings |\n| `edict_debug` | Execution tracing and crash diagnostics |\n| `edict_compose` | Combines composable program fragments into a module |\n| `edict_explain` | Explains AST nodes, errors, or compiler behavior |\n| `edict_export` | Packages a program as a UASF portable skill |\n| `edict_import_skill` | Imports and executes a UASF skill package |\n| `edict_generate_tests` | Generates tests from Z3-verified contracts |\n| `edict_replay` | Records and replays deterministic execution traces |\n| `edict_deploy` | Compiles and deploys an Edict program to edge runtimes (Cloudflare Workers) |\n| `edict_invoke` | Invokes a deployed Edict WASM service via HTTP |\n| `edict_invoke_skill` | Invokes a UASF skill package directly |\n| `edict_package` | Packages a compiled program as a deployable skill bundle |\n| `edict_support` | Returns diagnostics and environment info for troubleshooting |\n\n### MCP Resources\n\n| URI | Description |\n|---|---|\n| `edict://schema` | The full AST JSON Schema |\n| `edict://schema/minimal` | Minimal schema variant for token-efficient bootstrap |\n| `edict://examples` | All example programs |\n| `edict://errors` | Machine-readable error catalog |\n| `edict://schema/patch` | JSON Schema for the AST patch protocol |\n| `edict://guide` | Agent bootstrap guide for MCP-first onboarding |\n| `edict://support` | Diagnostics and environment info |\n\n## Example Program\n\nA \"Hello, World!\" in Edict's JSON AST:\n\n```json\n{\n \"kind\": \"module\",\n \"id\": \"mod-hello-001\",\n \"name\": \"hello\",\n \"imports\": [],\n \"definitions\": [\n {\n \"kind\": \"fn\",\n \"id\": \"fn-main-001\",\n \"name\": \"main\",\n \"params\": [],\n \"effects\": [\"io\"],\n \"returnType\": { \"kind\": \"basic\", \"name\": \"Int\" },\n \"contracts\": [],\n \"body\": [\n {\n \"kind\": \"call\",\n \"id\": \"call-print-001\",\n \"fn\": { \"kind\": \"ident\", \"id\": \"ident-print-001\", \"name\": \"print\" },\n \"args\": [\n { \"kind\": \"literal\", \"id\": \"lit-msg-001\", \"value\": \"Hello, World!\" }\n ]\n },\n { \"kind\": \"literal\", \"id\": \"lit-ret-001\", \"value\": 0 }\n ]\n }\n ]\n}\n```\n\n## The Agent Loop\n\nThe core design: an agent submits an AST → the compiler validates it → if wrong, returns a `StructuredError` with enough context for the agent to self-repair → the agent fixes it → resubmits.\n\n```typescript\n// 1. Agent reads the schema to learn the AST format\nconst schema = edict_schema();\n\n// 2. Agent writes a program (may contain errors)\nconst program = agentWritesProgram(schema);\n\n// 3. Compile — returns structured errors or WASM\nconst result = edict_compile(program);\n\nif (!result.ok) {\n // 4. Agent reads errors and fixes the program\n // Errors include: nodeId, expected type, candidates, counterexamples\n const fixed = agentFixesProgram(program, result.errors);\n // 5. Resubmit\n return edict_compile(fixed);\n}\n\n// 6. Run the WASM\nconst output = edict_run(result.wasm);\n```\n\n## Architecture\n\n```\nsrc/\n├── ast/ # TypeScript interfaces for every AST node\n├── validator/ # Schema validation (structural correctness)\n├── resolver/ # Name resolution (scope-aware, with Levenshtein suggestions)\n├── checker/ # Type checking (bidirectional, with unit types)\n├── effects/ # Effect checking (call-graph propagation)\n├── contracts/ # Contract verification (Z3/SMT integration)\n├── codegen/ # WASM code generation (pure-JS encoder)\n│ ├── codegen.ts # IR → WASM module orchestration\n│ ├── compile-ir-expr.ts # IR expression compilation\n│ ├── compile-ir-*.ts # Specialized IR compilers (calls, data, match, scalars)\n│ ├── runner.ts # WASM execution (Node.js WebAssembly API)\n│ ├── host-adapter.ts # EdictHostAdapter interface + platform adapters\n│ ├── closures.ts # Closure capture and compilation\n│ ├── hof-generators.ts # Higher-order function WASM generators\n│ ├── wasm-encoder.ts # Pure-JS WASM binary encoder (replaced binaryen)\n│ ├── wasm-interpreter.ts # Pure-JS WASM interpreter (no WebAssembly API needed)\n│ ├── recording-adapter.ts # Execution recording for replay\n│ ├── replay-adapter.ts # Deterministic replay from recorded traces\n│ └── string-table.ts # String interning for WASM memory\n├── ir/ # Mid-level IR (lowering, optimization)\n├── builtins/ # Builtin registry and domain-specific builtins\n├── compact/ # Compact AST format (token-efficient for agents)\n├── compose/ # Composable program fragments\n├── deploy/ # Edge deployment scaffolding (Cloudflare Workers)\n├── incremental/ # Incremental checking (dependency graph + diff)\n├── lint/ # Non-blocking quality warnings\n├── patch/ # Surgical AST patching by nodeId\n├── migration/ # Schema version migration (auto-upgrade older ASTs)\n├── skills/ # Skill packaging and invocation\n├── mcp/ # MCP server (tools + resources + prompts)\n└── errors/ # Structured error types\n\ntests/ # 2675 tests across 136 files\nexamples/ # 41 example programs (⭐→⭐⭐⭐ difficulty in README)\nschema/ # Auto-generated JSON Schema\n```\n\n## Type System\n\n| Type | Example |\n|---|---|\n| Basic | `Int`, `Int64`, `Float`, `String`, `Bool` |\n| Array | `Array` |\n| Option | `Option` |\n| Result | `Result` |\n| Record | `Point { x: Float, y: Float }` |\n| Enum | `Shape = Circle { radius: Float } \\| Rectangle { w: Float, h: Float }` |\n| Refinement | `{ i: Int \\| i > 0 }` — predicates verified by Z3 |\n| Function | `(Int, Int) -> Int` |\n\n## Effect System\n\nFunctions declare their effects. The compiler enforces:\n\n- A `pure` function cannot call an `io` function\n- Effects propagate through the call graph\n- Missing effects are detected and reported\n\nEffects: `pure`, `reads`, `writes`, `io`, `fails`\n\n## Contract Verification\n\nPre/post conditions are verified at compile time using Z3:\n\n```json\n{\n \"kind\": \"post\",\n \"id\": \"post-001\",\n \"condition\": {\n \"kind\": \"binop\", \"id\": \"binop-001\", \"op\": \">\",\n \"left\": { \"kind\": \"ident\", \"id\": \"ident-result-001\", \"name\": \"result\" },\n \"right\": { \"kind\": \"ident\", \"id\": \"ident-x-001\", \"name\": \"x\" }\n }\n}\n```\n\nZ3 either proves `unsat` (contract holds ✅) or returns `sat` with a concrete counterexample the agent can reason about.\n\n## Contributing\n\nWe welcome contributions from agents and humans alike. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding standards, and the PR workflow.\n\n**Looking for a place to start?** Check issues labeled [`good first issue`](https://github.com/Sowiedu/Edict/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for the full development plan, [FEATURE_SPEC.md](FEATURE_SPEC.md) for the language specification, and [Crystallized Intelligence](docs/crystallized-intelligence.md) for how agents store and reuse verified WASM skills.\n\n## Support\n\nEdict is free and open source under the MIT license. If your agents find it valuable, consider [sponsoring its development](https://github.com/sponsors/Sowiedu).\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 14307,
"sha": "4438093cb02e3a0fe2e6519944d7f90782bfcbbc437b9b1df0a155957a504ac2",
"repo_slug": "sowiedu/edict",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_sowiedu_edict_a22caab8/readme"
}