From 068cf51b0ffc6fb9af05320ad748397b080ea791 Mon Sep 17 00:00:00 2001 From: onatozmenn Date: Wed, 12 Aug 2026 17:12:22 +0300 Subject: [PATCH] Tell the truth about the backend and adoption --- README.md | 19 +++++++++---------- ROADMAP.md | 14 ++++++++------ design/01-principles.md | 11 ++++++----- design/05-backend.md | 14 ++++++++------ 4 files changed, 31 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 05323c4b..82721637 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,15 @@ A contract-first language where a function signature is a promise the compiler checks. Built for code that machines write and humans review. -> **Status: it runs.** The compiler lexes, parses, resolves names, type checks and checks -> effect rows, and a tree walking interpreter executes `test` blocks and `main` with -> contracts enforced at runtime. Programs get their authority from a `System` capability -> handed to `main`, and a `Dir` narrows to a subdirectory and cannot be walked back out of. -> There is no code generation, and what a run costs without it has been measured rather -> than guessed at: `design/01-principles.md` has the table and the reason a compiler is not -> the next thing. Criticism of the design is still the most useful -> contribution. See [issue #228](https://github.com/deed-lang/deed/issues/228) for where -> this is going, and [ROADMAP.md](ROADMAP.md) for what stands between a language one -> person writes and a language GitHub names, measured rather than asserted. +> **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](ROADMAP.md) keeps that +> distinction and the commands that measure it. ## Getting it diff --git a/ROADMAP.md b/ROADMAP.md index f296068f..d95adb25 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -42,7 +42,7 @@ So there is exactly one path, and it runs through other people's repositories. --- -## 2. Where we are, measured on 2026-08-08 +## 2. Where we are, measured on 2026-08-12 | Thing | Measured | How | | --- | --- | --- | @@ -52,8 +52,8 @@ So there is exactly one path, and it runs through other people's repositories. | Repositories containing Deed source | **1** | same | | Stars | **7** | `gh api repos/deed-lang/deed` | | Forks | **0** | same | -| Release downloads, all 10 releases | **17** | `gh api …/releases` | -| Repo age | **14 days** | created 2026-07-25 | +| Release downloads, all 12 releases | **26** | `gh api …/releases` | +| Repo age | **18 days** | created 2026-07-25 | The distance is not 2000 − 87. It is 2000 − 0, because the owner is filtered out. At a typical ~10 `.deed` files per project, the shape of the target is: @@ -95,13 +95,13 @@ word and the same extension, which is worth knowing for two reasons: ```powershell # The only number that matters: files that are Deed, in repos we do not own. gh api -X GET search/code --raw-field q='extension:deed "ensures" -user:deed-lang' --jq '.total_count' -# 2026-08-08: 0 +# 2026-08-12: 0 # The control. If this one is also 0, the query broke — it is not that Deed # vanished. A metric that cannot tell "nothing there" from "nothing measured" # is worse than no metric. gh api -X GET search/code --raw-field q='extension:deed "ensures"' --jq '.total_count' -# 2026-08-08: 8 +# 2026-08-12: 8 # Distribution: how many distinct owners, not just how many files. gh api -X GET search/code --raw-field q='extension:deed "ensures" -user:deed-lang' --paginate ` @@ -165,7 +165,7 @@ result, so the scaffold cannot rot into something that does not compile. README used to say `cargo install --path crates/deed-cli` and nothing else. There was no `curl | sh`, no Homebrew formula, no winget package, and no -`cargo install deed`. Seventeen downloads across ten releases is what that +`cargo install deed`. Twenty-six downloads across twelve releases is what that cost. `install.sh` and `install.ps1` now fetch the release asset for the machine, @@ -402,6 +402,8 @@ tests the premise rather than the execution. - Everything Linguist needs from **us** is done. - Everything Linguist needs from **the world** is at zero. Not near zero: the six files that carry the extension elsewhere are somebody else's format. +- Stage 1 is still open on 2026-08-12: the Deed-specific outside-owner query is + **0** while its control is **8**. - The gap is not technical, and no amount of compiler work closes it. - Stage 0 is closed. Somebody who hears about Deed can install it in one line, or with `cargo install deed-lang`, and `deed new` gives them a project that diff --git a/design/01-principles.md b/design/01-principles.md index 19011151..e697e5c0 100644 --- a/design/01-principles.md +++ b/design/01-principles.md @@ -270,11 +270,12 @@ just wastes the time of anyone who takes this seriously. ### What a run costs -The other one, and the one people ask about first. There is no code generation: a tree -walking interpreter runs `test` blocks and `main`. Nothing had measured what that costs, -which meant the question everybody starts with, whether a compiler should be a bytecode -machine or native code, had nothing under it. The question in front of it is what a run -spends its time on now. +The other one, and the one people ask about first. When this measurement was written, only +the tree-walking interpreter ran `test` blocks and `main`; the WebAssembly backend came +later. Nothing had measured what the interpreter cost, which meant the question everybody +started with, whether a compiler should be a bytecode machine or native code, had nothing +under it. This table is the baseline that made the backend a decision about embedding and +authority rather than a guessed performance project. `cargo run -p deed-driver --example interpreting --release` asks. On one machine: diff --git a/design/05-backend.md b/design/05-backend.md index ce782898..ff663d10 100644 --- a/design/05-backend.md +++ b/design/05-backend.md @@ -2,12 +2,14 @@ ## Why this exists -There is no code generation today: `deed run`, `deed check` and `deed test` all go through -a tree-walking interpreter, and `design/01-principles.md`'s P10 section measured what that -costs. That measurement is still open. Call cost has an argument list and a binding that -cost something, a frame pool was tried and ruled out, and a slot per name was measured and -found not to matter. Nothing in this document depends on that question closing, and it does -not reopen it. +There is code generation today. `deed check` stays in the checking pipeline; `deed run` and +`deed test` use the tree-walking reference interpreter by default and use the WebAssembly +backend with `--compiled`; `deed build` writes a core module and can also write a component. +`design/01-principles.md`'s P10 table measured the interpreter before that backend existed. +It remains the baseline that explains why compilation was built for embedding and structural +authority rather than from an unmeasured speed claim. Call cost has an argument list and a +binding that cost something, a frame pool was tried and ruled out, and a slot per name was +measured and found not to matter. The reason to compile Deed is not that the interpreter is slow. It is that an interpreter is a single artifact: it needs its own toolchain, its own process, and it cannot be embedded