l4-computational-law

L4 with IDE

L4 is a domain-specific programming language for law. It formalizes legal rules and contracts as executable specifications, bringing software engineering rigor to legal drafting and analysis.

This repository contains the L4 compiler, IDE tooling (VS Code extension, LSP, REPL, web editor), and a decision service that exposes L4 rules as REST APIs and MCP tools.

What You Get From a Single L4 File

• REST APIs — Expose functions as HTTP endpoints with @export annotations
• AI tool integration — MCP server for Claude, Cursor, and VS Code Copilot; WebMCP for in-browser agents
• Interactive visualizations — Ladder diagrams and evaluation traces rendered via GraphViz
• Audit-grade explainability — Every evaluation produces a trace you can follow from the top-level question down to the deciding condition
• Test suites — Golden-file tests and assertions
• Generated schemas — OpenAPI 3.0 specs and JSON schemas for integration

Getting Started

• Install the VS Code extension: L4 Rules-as-code on the Marketplace
• Try the web editor: https://jl4.legalese.com/
• Learn L4: Foundation Course — no prior programming experience required
• Full documentation: doc/README.md

Repository Layout

Haskell (Cabal):

Package	Purpose
jl4-core	Core language (parser, typechecker, evaluator)
jl4	CLI tool and JSON schema generator
jl4-lsp	Language Server Protocol for IDE support
jl4-repl	Interactive REPL
jl4-service	REST API for decision evaluation
jl4-websessions	Session persistence service
jl4-query-plan	Query planning utilities
jl4-actus-analyzer	Static analyzer classifying L4 contracts by ACTUS / FIBO
jl4-wasm	WebAssembly build of L4 for browser/Node.js
jl4-mlir	MLIR/WASM compiler backend: L4 → .wasm decision binary

TypeScript (npm workspaces + Turborepo):

Package	Purpose
ts-apps/vscode	VS Code extension
ts-apps/jl4-web	Web-based editor (Svelte)
ts-shared	Shared libraries (RPC client, visualizers)

Documentation: See doc/ for the language reference, tutorials, courses, and concept guides.

Building From Source

cabal build all          # Haskell
npm ci && npm run build  # TypeScript

See AGENTS.md for repository conventions and workflow, and dev-start.sh for running services locally.

Requirements: GHC 9.10.2, Cabal 3.10+, Node.js ≥ 20, and GraphViz (dot). Nix users can run nix-shell nix/shell.nix for a ready environment.

The REPL

An interactive Read-Eval-Print Loop for exploring L4 code:

cabal run jl4-repl -- path/to/file.l4

The REPL provides live evaluation, module reloading (:load, :reload), query planning (:decides, :queryplan), and trace output (:trace, :traceascii, :tracefile). See jl4-repl/README.md for the full command list.

VS Code Extension

Provides syntax highlighting, type checking, inline evaluation, @export previews, deployment management, and an automatically-registered local MCP server that bridges Claude Code, Cursor, and VS Code Copilot to your L4 code. Connects to Legalese Cloud or a self-hosted jl4-service instance. See ts-apps/vscode/README.md.

Trace Visualization

Every tool in this repo can render an L4 evaluation as a GraphViz diagram:

• CLI: l4 trace myfile.l4 > trace.dot, then dot -Tsvg trace.dot > trace.svg (or l4 trace myfile.l4 --format svg -o out/ to generate SVG files directly)
• REPL: :trace <expression>, or :tracefile traces/session to capture numbered .dot files
• Decision Service: POST /deployments/{id}/functions/{fn}/evaluation?trace=full&graphviz=true

Install GraphViz with brew install graphviz or apt-get install graphviz to render PNG/SVG outputs.