What is Angl

Angl is an experiment in contract-checked code regeneration. You commit a readable chapter of English behavior plus executable expectation examples. A configured compiler agent turns that chapter into ordinary code. A black-box judge accepts the generated edition only if the examples pass.

The semantic model is four words:

contract pins, intent guides

English helps the compiler choose an implementation. It never decides correctness. Only executable examples do.

Why

Generated code is often the least interesting part of a system. The behavior you meant to preserve is usually the interface plus the observable cases that must keep passing.

Angl tests that idea directly:

• commit the intent and executable examples
• generate code from the spec
• regenerate when the ecosystem changes
• accept the new artifact only if the same contract still passes

A concrete proof from the repo: old generated code imported BaseSettings from pydantic. Pydantic v2 moved it to pydantic-settings, so the old artifact failed hard under the newer dependency set. The unchanged .angl chapter was recompiled, and the new artifact passed the same contract cases. The durable asset is the contract, not the generated source.

The pipeline

specs/x.angl
  -> parse
  -> compile with the configured model provider
  -> write build/<func>.<target> plus generated adapters
  -> run each expectation through the judge adapter
  -> accept only if every expectation passes

The verifier never imports the generated edition directly. It runs the judge adapter as a subprocess and compares JSON input and output. That is the core language-neutrality boundary: the judge cannot even tell what language the artifact is written in.

The three invariants

These are the language. Any change that violates one of them is not Angl.

1. Source depends on no target language. A chapter is English plus JSON data.
2. The contract is the meaning. The judge is the sole arbiter of correct.
3. The target is disposable and swappable. Generated editions are build outputs, gitignored, regenerated, and never edited by hand.

Trickle-down coding

The intended workflow:

1. Write chapters for the stable product boundaries.
2. Add expectation examples for behavior that must not drift.
3. Let the compiler agent generate ordinary code for each chapter.
4. Verify every chapter black-box.
5. Compile dependents after dependencies, so verified behavior flows upward.

Mechanically, Angl uses a topological order: dependencies compile first, then the chapters that use them. That is the part that keeps downstream code from silently diverging.

What Angl is not

• Not a general-purpose programming language. You never write control flow, variables, or evaluation order. It is a specification language, in the lineage of TLA+, protobuf/IDL, Dafny, and property testing, with an LLM backend. That lineage is why it tolerates ambiguity a normal compiler cannot: the English suggests meaning, the contract fixes it.
• Not model self-evaluation. The judge is decidable: finite cases, black-box I/O comparison, always terminates. English alone cannot decide correctness without collapsing back into asking the model to grade itself.
• Not a proof of correctness. Regeneration is a way to ask a model for a new artifact, then reject it unless the checked contract still passes. Untested behavior is unspecified.

Status

Angl is production-interesting, not production-ready. The core toolchain, the repair loop, mixed-language targets, Postgres-backed fixtures, and a sandboxed distributed runtime are proven locally. See Limits for the honest assessment.