Deed

A contract-first language where a function signature is a promise the compiler checks. Built for code that machines write and humans review.

Status: the toolchain works; adoption is the open question. The compiler lexes, parses, resolves names, checks types, contracts and effect rows, and runs programs through either the reference interpreter or a WebAssembly backend. deed build writes a core module, and --component writes a component when its exported values cross the canonical ABI. Programs get authority from explicit capabilities, with the same host rules in both engines. The largest unfinished technical work is value reclamation and wider component adapters; the largest project risk is simpler and measured: no public repository outside this organization contains known Deed source yet. ROADMAP.md keeps that distinction and the commands that measure it.

Getting it

One line, on Linux or an Apple-silicon Mac:

$ curl -fsSL https://raw.githubusercontent.com/deed-lang/deed/main/install.sh | sh

On Windows:

> irm https://raw.githubusercontent.com/deed-lang/deed/main/install.ps1 | iex

Either one downloads the release asset for your machine, refuses it if its hash is not the one the release published, and puts a single file in your own profile. It never asks for a password, because it never writes outside it. The checksums come from the same release as the binary, so that catches a corrupted download and does not catch a compromised release; saying so is better than a sha256 that reads like it proves more than it does.

By hand instead: every release carries a deed binary for Linux, macOS and Windows. Take the one for your machine from releases, unpack it, and run it. There is nothing else to install: the compiler, the formatter, the test runner and the language server are all in that one file.

Start with the tutorial if you want one program built up one step at a time.

$ tar xzf deed-v0.2.13-x86_64-unknown-linux-gnu.tar.gz
$ ./deed-v0.2.13-x86_64-unknown-linux-gnu/deed --version
deed 0.2.13

With Rust 1.88 or newer instead, from crates.io or from a clone:

$ cargo install deed-lang
$ cargo install --path crates/deed-cli

deed on crates.io belongs to somebody else, so the package is deed-lang. The binary it installs is deed; the package README keeps the short install and MCP entry points next to the package metadata.

What the version promises. 0.x says the language can still move, so a file that compiles against one minor release may not compile against the next. Breaking moves are called out in release notes, and deed fix carries the mechanical part when possible. The full policy, including diagnostics and std/, is in design/07-versioning.md.

Starting something

deed new writes a project rather than leaving you to work out the module header and the file layout from this repository. The name becomes both the directory and the module path.

$ deed new greeter
greeter/greeter.deed
greeter/main.deed

next: cd greeter && deed test .

$ cd greeter
$ deed test .
./greeter.deed
  ok    a greeting carries the name it was given
  ok    there is no greeting for nobody
  ok    property greeting (100 cases)

3 passed, 0 failed

$ deed run main.deed
hello, world

Three tests from two files, and only two of them were written down. The third is generated from the contract on greeting, which is what a signature being a promise buys. There is no manifest, because a manifest here says where code outside your tree lives and a new project has none.

crates/deed-cli/tests/new.rs runs that command into a temporary directory on every commit and then checks, tests, runs and format-checks what came out, so the scaffold cannot rot into something that no longer compiles.

What it looks like on real code

$ deed run examples/config.deed --dir examples
found it
`..` would leave the directory, and there is no way out of a `Dir`
`../Cargo.toml` is not a single name, and a `Dir` only takes one at a time
`/etc/passwd` is not a single name, and a `Dir` only takes one at a time
`nowhere` is not there
used the fallback

$ deed test examples/
examples/counter.deed
  ok    bumping twice adds twice
  ...
examples/transfer.deed
  ok    moves the money and conserves the total
  ok    refuses to overdraw and leaves the ledger alone
  ok    refuses a currency mismatch and leaves the ledger alone

138 passed, 0 failed

That number used to be 102. Seven of those tests are in std/table now, because the table library stopped living under examples/ and a module that ships with the compiler is context rather than subject, so the corpus does not run its tests any more. Nothing was deleted: the modules that ship carry one hundred and ten tests of their own, and crates/deed-driver/tests/shipped.rs runs every one of them on every commit.

$ deed check examples/transfer.deed --obligations
obligations: 7 proven, 0 tested, 6 guarded
  guarded  examples/transfer.deed:94:5  transfer ensures ok
  ...
  proven   examples/transfer.deed:202:76  Positive

For an editor, see editors. VS Code now carries both syntax highlighting and a language-server client, while Helix and Neovim start the language server from a few lines of configuration and no plugin.

For a coding agent, deed mcp speaks the Model Context Protocol on stdin and stdout, so the machine writing the code can ask the compiler the same questions an editor does rather than scraping them out of terminal output. It holds no capability: a program arrives as text, the answer leaves as text, and a program whose row reaches a file is refused before it runs. Its official Registry name is mcp-name: io.github.deed-lang/deed. how-to/let-an-agent-use-the-compiler.md has the tool reference and the one line worth reading.

Every agent patch comes with a receipt

deed review compares the checked module set before a change with the one after it. The first receipt names newly declared authority and obligations that fell to a weaker contract tier:

$ deed review --before old/src --after src
receipt: review required
authority added (1)
  + billing/transfer/settle: Audit.note
obligation tier regressions (1)
  ! billing/transfer/settle: Positive proven -> guarded
guarded obligations added (0)

The paths may name files or directories, and imports are resolved independently on each side. --format json emits the same receipt as one stable object for an agent or CI job. Findings are informational unless a policy turns them into a gate: --deny-new-authority, --deny-weaker-promises and --deny-new-guarded each exit one when its own evidence is present, while still printing the receipt and a policy verdict. A side that does not check is refused rather than compared.

The same evidence is available to an agent as deed_review. It takes the before and after module sets as arrays of source text, resolves imports within each array, and applies the same three policies without opening a file. The CI guide is a complete pull-request workflow that compares the two commit trees rather than a runner's mutable working directory.

Demo

One clause in a function signature is the difference between two components. demo/README.md shows two functions that are identical except for one uses entry, compiles both to WebAssembly, and shows the import section of each module side by side. The test in crates/deed-driver/tests/demo.rs pins the host's refusal mechanically on every commit.

How-to guides

If you already know the language and want the shortest path to a specific task, start with how-to/README.md. Those pages index the existing corpus: checking a module set, writing tests, contracts and assert refuses, effects and capabilities, formatting, backend compilation, and editor setup.

The shipped library API is indexed separately in docs/std.md, with one page per module and every exported function held there by a documentation ratchet. deed doc <path>... writes the same page for any module of your own. There are no visibility modifiers here, so every declaration is API and a page is the signature, the row, the contract and the lines of its own tests that name it.

There is no REPL. A Deed input is a module of declarations, and deed run enters through main rather than evaluating a top-level expression. For quick experiments, use a scratch .deed file with deed check, deed test or deed run. The right browser answer is a playground that edits and runs a whole program in that same shape.

There is also a small conformance suite for checks that should hold across implementations.

Every .deed file here was written by one person, which is the largest open question about this language and not one the compiler can answer. benchmarks/README.md is where that stops being a sentence: a set of tasks, each with tests it does not show the author, and a scorer that reports not only whether an answer compiles and passes but how much of its contract the checker could prove.

User-visible language, diagnostics, library and tool changes are recorded in CHANGELOG.md, including programs that used to compile and no longer do.

The idea