edict-lang
The edict-lang server provides a full lifecycle MCP interface for AI agents to write, validate, compile, and execute programs in Edict—a statically-typed, effect-tracked language where programs are JSON ASTs (no text parsing). Structured error feedback enables self-repair loops.
Schema & Discovery
edict_schema: Retrieve the JSON Schema for valid Edict ASTs (full, minimal, compact, or agent-optimized formats)edict_version: Get compiler version and capability informationedict_examples: Access 41 example programs as JSON ASTsedict_errors: Get a machine-readable catalog of all error typesedict_explain: Get enriched repair context (pipeline stage, field metadata, example ASTs) for a structured error
Validation & Checking
edict_validate: Validate AST structure (field names, types, node kinds) without full compilationedict_check: Run the full semantic pipeline — name resolution, type checking, effect checking, and Z3/SMT contract verificationedict_lint: Non-blocking quality analysis returning warnings (unused variables, missing contracts, etc.)
AST Editing & Composition
edict_patch: Apply surgical patches to an AST by node ID (replace/delete/insert) and re-run the full check pipelineedict_compose: Combine multiple program fragments into a single module
Compilation & Execution
edict_compile: Compile a valid AST to a base64-encoded WebAssembly binaryedict_run: Execute a compiled WASM module in a sandboxed runtime with configurable timeout and memory limits (supportsrecord: truefor deterministic replay)edict_debug: Execute with debug instrumentation, returning call stack, crash location, and step countedict_replay: Re-execute a WASM module deterministically using a previously recorded replay token
Skill Packaging & Invocation
edict_export: Export an AST as a portable WASM skill package (UASF format) with manifest generationedict_package: Package a compiled module and WASM binary into a portable SkillPackage JSON with integrity checksumedict_import_skill: Import and execute a compiled skill package with checksum validationedict_invoke_skill: Execute a packaged SkillPackage directly
Deployment
edict_deploy: Deploy a program to a target (raw WASM binary or Cloudflare Workers bundle)edict_invoke: Invoke a deployed Edict WASM service via HTTP
Testing & Support
edict_generate_tests: Auto-generate test cases from Z3-verified contracts (boundary values and counterexamples)edict_support: Retrieve diagnostics, environment info, and sponsorship information
Compiles verified agent-generated programs into WebAssembly (WASM) binaries and provides a sandboxed execution environment with controlled host capabilities like filesystem and network access.
Edict
A programming language designed for AI agents. No parser. No syntax. Agents produce AST directly as JSON.
Edict 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.
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 → ExecuteFeatures
JSON AST — Programs are JSON objects, not text files. No lexer, no parser.
Structured errors — Every error is a typed JSON object with enough context for an agent to self-repair.
Type system —
Int,Float,String,Bool,Array<T>,Option<T>,Result<T,E>, records, enums, refinement types.Effect tracking — Functions declare
pure,reads,writes,io,fails. The compiler verifies consistency.Contract verification — Pre/post conditions verified at compile time by Z3 (via SMT). Failing contracts return concrete counterexamples.
WASM compilation — Verified programs compile to WebAssembly via a pure-JS encoder and run in Node.js.
MCP interface — All tools exposed via Model Context Protocol for direct agent integration.
Schema migration — ASTs from older schema versions are auto-migrated. No breakage when the language evolves.
Related MCP server: ZeroLang Agent Compiler MCP
Execution Model
Edict compiles to WebAssembly and runs in a sandboxed VM. This is a deliberate security decision — not a limitation:
No ambient authority — compiled WASM cannot access the filesystem, network, or OS unless the host explicitly provides those capabilities via the pluggable
EdictHostAdapterinterfaceCompile-time capability declaration — the effect system (
io,reads,writes,fails) lets the host inspect what a program requires before running itRuntime enforcement —
RunLimitscontrols execution timeout, memory ceiling, and filesystem sandboxingDefense-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
Host capabilities available through adapters: filesystem (sandboxed), HTTP, crypto (SHA-256, MD5, HMAC), environment variables, CLI arguments. New capabilities are added by extending EdictHostAdapter.
Quick Start
For AI Agents (MCP)
The fastest way to use Edict is through the MCP server — it exposes the entire compiler pipeline as tool calls:
npx edict-lang # start MCP server (stdio transport, no install needed)Or install locally:
npm install edict-lang
npx edict-lang # start MCP serverTwo calls to get started: edict_schema (learn the AST format) → edict_check (submit a program). See MCP Tools for the full tool list.
For Development
npm install
npm test # 2675 tests across 136 files
npm run mcp # start MCP server (stdio transport)Docker
Run the Edict MCP server in a container — no local Node.js required:
# 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/edictSupported platforms: linux/amd64, linux/arm64.
Browser
Run the Edict compiler entirely in the browser — no server required:
Bundle | Size | Phases | Use case |
| 318 KB | 1–3 (validate, resolve, typecheck, effects, lint, patch) | Lightweight checking |
| ~14 MB | 1–5 (+ WASM codegen, Z3 contracts, WASM execution) | Full compile & run |
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!"
}Note: ESM modules require HTTP serving. Use
npx serve .or any static server —file://won't work.
See examples/browser/index.html for a working example.
QuickJS (Sandboxed Environments)
The Edict compiler also runs inside QuickJS WASM — useful for sandboxed runtimes, edge workers, or embedding in other WASM applications:
Bundle | Size | Phases | Slowdown vs Node.js |
| 373 KB | 1–3 (validate, resolve, typecheck, effects) | ~3.7x |
| 932 KB | 1–5 (check + WASM compile) | ~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();Note:
quickjs-emscriptenis an optional peer dependency — install it alongsideedict-langto useEdictQuickJS. For fs-free environments, passbundleSourcedirectly instead of loading from disk.
See docs/quickjs-feasibility-report.md for full benchmarks and recommendations.
MCP Tools
Tool | Description |
| Returns the full AST JSON Schema — the spec for how to write programs |
| Returns compiler version and capability info |
| Returns 41 example programs as JSON ASTs (includes schema snippet) |
| Validates AST structure (field names, types, node kinds) |
| Full pipeline: validate → resolve names → type check → effect check → verify contracts |
| Compiles a checked AST to WASM (returns base64-encoded binary) |
| Executes a compiled WASM binary, returns output and exit code |
| Applies targeted AST patches by nodeId and re-checks |
| Returns machine-readable catalog of all error types |
| Runs non-blocking quality analysis and returns warnings |
| Execution tracing and crash diagnostics |
| Combines composable program fragments into a module |
| Explains AST nodes, errors, or compiler behavior |
| Packages a program as a UASF portable skill |
| Imports and executes a UASF skill package |
| Generates tests from Z3-verified contracts |
| Records and replays deterministic execution traces |
| Compiles and deploys an Edict program to edge runtimes (Cloudflare Workers) |
| Invokes a deployed Edict WASM service via HTTP |
| Invokes a UASF skill package directly |
| Packages a compiled program as a deployable skill bundle |
| Returns diagnostics and environment info for troubleshooting |
MCP Resources
URI | Description |
| The full AST JSON Schema |
| Minimal schema variant for token-efficient bootstrap |
| All example programs |
| Machine-readable error catalog |
| JSON Schema for the AST patch protocol |
| Agent bootstrap guide for MCP-first onboarding |
| Diagnostics and environment info |
Example Program
A "Hello, World!" in Edict's JSON AST:
{
"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 }
]
}
]
}The Agent Loop
The 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.
// 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);Architecture
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 SchemaType System
Type | Example |
Basic |
|
Array |
|
Option |
|
Result |
|
Record |
|
Enum |
|
Refinement |
|
Function |
|
Effect System
Functions declare their effects. The compiler enforces:
A
purefunction cannot call aniofunctionEffects propagate through the call graph
Missing effects are detected and reported
Effects: pure, reads, writes, io, fails
Contract Verification
Pre/post conditions are verified at compile time using 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 either proves unsat (contract holds ✅) or returns sat with a concrete counterexample the agent can reason about.
Contributing
We welcome contributions from agents and humans alike. See CONTRIBUTING.md for setup instructions, coding standards, and the PR workflow.
Looking for a place to start? Check issues labeled good first issue.
Roadmap
See ROADMAP.md for the full development plan, FEATURE_SPEC.md for the language specification, and Crystallized Intelligence for how agents store and reuse verified WASM skills.
Support
Edict is free and open source under the MIT license. If your agents find it valuable, consider sponsoring its development.
License
Available Tools
22 toolsedict_checkA
Run the full semantic checker (name resolution, type checking, effect checking, contract verification) on an AST. Supports single module (ast) or multi-module (modules array) input.
Inputs: ast, modules.
edict_compileA
Compile a semantically valid Edict AST into a WebAssembly module. Returns the WASM binary encoded as a base64 string. Supports single module (ast) or multi-module (modules array) input.
Inputs: ast, modules.
edict_composeA
Compose multiple Edict program fragments into a single module. Fragments declare what they provide and require, enabling independent validation and incremental program generation.
Inputs: fragments (required), moduleName, moduleId, check.
edict_debugA
Execute an Edict program with debug instrumentation. Compiles the AST with call-stack tracing, runs it, and returns structured crash diagnostics including call stack at crash time, crash location with nodeId, and step count. Use this instead of edict_compile + edict_run when debugging runtime failures — the crash location and call stack enable targeted fixes without guessing.
Inputs: ast (required), options.
edict_deployA
Deploy an Edict program to a target. Runs the full pipeline (validate → check → compile) then packages for the specified target. Targets: 'wasm_binary' (returns WASM + metadata), 'cloudflare' (generates Worker bundle).
Inputs: ast (required), target (required), config.
edict_errorsD
Inputs: no named parameters.
edict_examplesD
Inputs: no named parameters.
edict_explainA
Given a structured error, returns enriched repair context: pipeline stage, field metadata, example ASTs, and repair strategy.
Inputs: error (required).
edict_exportB
Export an Edict AST as a portable WASM skill package with validation and manifest generation.
Inputs: ast (required), metadata.
edict_generate_testsA
Auto-generate structured test cases from Z3-verified contracts. For proven contracts, extracts boundary input values and expected outputs from Z3 models. For failing contracts, extracts counterexample inputs as regression tests. Returns an array of GeneratedTest objects — each with function name, input values, expected output, and source (boundary/counterexample). Use this to get free tests from formal specifications without writing them manually.
Inputs: ast (required).
edict_import_skillC
Import and execute a compiled Edict WASM skill package, validating its checksum.
Inputs: skill (required), limits.
edict_invokeB
Invoke a deployed Edict WASM service via HTTP. Sends a request to the given URL with optional input and returns the structured result. Completes the deploy → invoke round-trip.
Inputs: url (required), input, method, timeoutMs, +1 more.
edict_invoke_skillB
Execute a packaged Edict skill — load WASM from a SkillPackage, verify integrity checksum, and run it. Returns structured output with exit code and return value.
Inputs: skill (required), limits.
edict_lintA
Run non-blocking lint analysis on an Edict AST. Returns quality warnings (unused variables, missing contracts, oversized functions, redundant effects, etc.) without blocking compilation. Warnings use the same structured format as errors but with severity: 'warning'.
Inputs: ast (required).
edict_packageA
Package a compiled Edict module + WASM binary into a portable SkillPackage. Input: the module AST (same one sent to edict_compile) + the base64 WASM string returned by edict_compile. Output: a SkillPackage JSON with interface metadata, verification info, integrity checksum, and the embedded WASM.
Inputs: ast (required), wasm (required), metadata.
edict_patchA
Apply surgical patches to an Edict AST by nodeId, then run the full check pipeline. Use this to fix errors without resubmitting the entire AST. Each patch specifies a nodeId, an operation (replace/delete/insert), and the relevant field/value.
Inputs: ast (required), patches (required), returnAst.
edict_replayA
Re-execute a WASM module using a previously recorded replay token for deterministic reproduction of runtime behavior. All non-deterministic host responses (random values, timestamps, HTTP responses, file IO) are replayed from the token instead of calling real host functions. Use this to reproduce exact failures or verify fixes against known execution traces.
Inputs: wasmBase64 (required), replayToken (required), limits.
edict_runA
Execute a compiled WebAssembly module (provided as base64) in a sandboxed runtime. The WASM VM has no ambient authority — filesystem, network, and crypto access are provided exclusively through host adapters. Returns standard output, exit code, and any sandbox limit errors. Supports optional execution limits (timeout, memory, sandbox directory) and external WASM modules for import interop. Set record: true to capture all non-deterministic host responses in a replay token for deterministic reproduction.
Inputs: wasmBase64 (required), limits, externalModules, record.
edict_schemaA
Return the JSON Schema defining valid Edict AST programs. Use format 'agent' for one-call bootstrapping (minimal schema + compact maps + builtins + effects).
Inputs: format.
edict_supportB
Returns structured sponsorship and support information for the Edict project
Inputs: no named parameters.
edict_validateA
Validate an Edict AST against the compiler's JSON schema without typing or compiling. Use this as a first pass.
Inputs: ast (required).
edict_versionD
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools have distinct purposes clearly described, such as edict_compile for compilation and edict_run for execution. However, some overlap exists between edict_deploy (which includes validation, checking, and compilation) and other tools like edict_validate and edict_compile, which could cause confusion about when to use each. The descriptions generally help clarify boundaries, but the pipeline overlap is noticeable.
All tool names follow a consistent verb_noun pattern with the prefix 'edict_' and snake_case throughout, such as edict_check, edict_compile, and edict_deploy. There are no deviations in naming conventions, making the set predictable and easy to parse for agents.
With 22 tools, the count feels heavy for a language server, bordering on excessive. While the domain (Edict language processing) is complex, many tools like edict_errors, edict_examples, and edict_version lack descriptions, suggesting they might be trivial or redundant. A more streamlined set of 10-15 core tools would likely suffice without losing functionality.
The tool surface covers a comprehensive lifecycle from validation (edict_validate) to deployment (edict_deploy) and debugging (edict_debug), with good support for testing (edict_generate_tests) and packaging (edict_package). Minor gaps exist, such as no explicit tool for editing or refactoring code beyond edict_patch, but agents can work around this using existing tools for most workflows in the Edict domain.
Maintenance
Related MCP Connectors
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
38 MCP tools: Rust computation, Discovery, composition, counterexample scans and signed checks.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceTACIT (Tracked Agent Capabilities In Types) is a safety harness for AI agents. Instead of calling tools directly, agents write code in Scala 3 with capture checking: a type system that statically tracks capabilities and enforces that agent code cannot forge access rights, cannot perform effects beyond its budget, and cannot leak information from pure sub-computations. It provides an MCP interface,152Apache 2.0
- FlicenseNot gradedqualityDmaintenancePaid remote MCP for ZeroLang, providing tools to compile ZeroLang programs, run fixtures, explain compile errors, and export agent plans, with structured receipts and audit logs.-
- AlicenseAqualityCmaintenanceContract-first programming language with a local MCP server for checking types, effects, capabilities, and contracts in agent-written modules. Its review tool compares before and after source sets and returns receipts for new authority, weaker promise tiers, and new Guarded runtime obligations.79Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to navigate and verify a contract-backed semantic graph of TypeScript backends, inspect change impact, run checks, explain failures, and draft human-reviewable contracts through bounded MCP tools and matching JSON CLI output.Apache 2.0