Skip to main content
Glama

Edict

CI License: MIT Node.js MCP

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 → Execute

Features

  • 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 EdictHostAdapter interface

  • Compile-time capability declaration — the effect system (io, reads, writes, fails) lets the host inspect what a program requires before running it

  • Runtime enforcement — RunLimits controls execution timeout, memory ceiling, and filesystem sandboxing

  • 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

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 server

Two 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/edict

Supported platforms: linux/amd64, linux/arm64.

Browser

Run the Edict compiler entirely in the browser — no server required:

Bundle

Size

Phases

Use case

edict-lang/browser

318 KB

1–3 (validate, resolve, typecheck, effects, lint, patch)

Lightweight checking

edict-lang/browser-full

~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

dist/edict-quickjs-check.js

373 KB

1–3 (validate, resolve, typecheck, effects)

~3.7x

dist/edict-quickjs-full.js

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-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.

See docs/quickjs-feasibility-report.md for full benchmarks and recommendations.

MCP Tools

Tool

Description

edict_schema

Returns the full AST JSON Schema — the spec for how to write programs

edict_version

Returns compiler version and capability info

edict_examples

Returns 41 example programs as JSON ASTs (includes schema snippet)

edict_validate

Validates AST structure (field names, types, node kinds)

edict_check

Full pipeline: validate → resolve names → type check → effect check → verify contracts

edict_compile

Compiles a checked AST to WASM (returns base64-encoded binary)

edict_run

Executes a compiled WASM binary, returns output and exit code

edict_patch

Applies targeted AST patches by nodeId and re-checks

edict_errors

Returns machine-readable catalog of all error types

edict_lint

Runs non-blocking quality analysis and returns warnings

edict_debug

Execution tracing and crash diagnostics

edict_compose

Combines composable program fragments into a module

edict_explain

Explains AST nodes, errors, or compiler behavior

edict_export

Packages a program as a UASF portable skill

edict_import_skill

Imports and executes a UASF skill package

edict_generate_tests

Generates tests from Z3-verified contracts

edict_replay

Records and replays deterministic execution traces

edict_deploy

Compiles and deploys an Edict program to edge runtimes (Cloudflare Workers)

edict_invoke

Invokes a deployed Edict WASM service via HTTP

edict_invoke_skill

Invokes a UASF skill package directly

edict_package

Packages a compiled program as a deployable skill bundle

edict_support

Returns diagnostics and environment info for troubleshooting

MCP Resources

URI

Description

edict://schema

The full AST JSON Schema

edict://schema/minimal

Minimal schema variant for token-efficient bootstrap

edict://examples

All example programs

edict://errors

Machine-readable error catalog

edict://schema/patch

JSON Schema for the AST patch protocol

edict://guide

Agent bootstrap guide for MCP-first onboarding

edict://support

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 Schema

Type System

Type

Example

Basic

Int, Int64, Float, String, Bool

Array

Array<Int>

Option

Option<String>

Result

Result<String, String>

Record

Point { x: Float, y: Float }

Enum

Shape = Circle { radius: Float } | Rectangle { w: Float, h: Float }

Refinement

{ i: Int | i > 0 } — predicates verified by Z3

Function

(Int, Int) -> Int

Effect System

Functions declare their effects. The compiler enforces:

  • A pure function cannot call an io function

  • Effects 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

MIT

Available Tools

22 tools
edict_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

    C2.9/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      TACIT (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,
      152
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Contract-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.
      7
      9
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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