contract pins, intent guides

Behavior is the source code.

An .angl chapter is English behavior plus executable examples. A compiler agent turns it into ordinary code. A black-box judge accepts the generated edition only if every example passes.

A complete chapter
specs/fetch_price.angl
fetch_price.anglthis is the committed source, in full
# Fetch Price

> Boundary: `fetch_price(url: string) -> number` > Runs as: `python`
## Purpose Provide the price value from a JSON HTTP response. ## Behavior Fetch JSON from the given URL and return the `price` field as a number. If the field is missing, fail with an error that mentions `price`. ## Examples ### The service returns a price When the URL serves a price, the chapter returns that price. Fixture `http_fixture`: ```json { "price": 19.99 } ``` Returns: ```json 19.99 ``` ### The service omits the price When the URL serves JSON without a price field, the chapter rejects it. Fixture `http_fixture`: ```json {} ``` Fails with error containing: price
The Python behind this boundary is a build artifact. It is generated, verified, and never edited by hand.
The pipeline
.angl chapter
Title, typed boundary, English behavior, executable examples. The only committed source.
compiler agent
An LLM writes an edition in the chapter's target: Python, Node, Ruby, Go, Rust, TypeScript, or a native bundle.
black-box judge
Runs every example over a JSON shim, as a subprocess. It never imports the code and cannot tell what language it is.
accepted edition
Disposable, gitignored, regenerated when anything changes. Rejected editions go back to the compiler with the failure.
Polyglot by chapter

One composed program can cross Python, Node, Ruby, Go, Rust, and TypeScript, because each chapter picks its own target and every seam is contract-verified.

picnic_normalize → python
picnic_menu → node
picnic_pack → ruby
Regeneration heals

A real pydantic v1 to v2 break rotted a generated artifact. The unchanged chapter was recompiled under the new pin and passed the same contract. The durable asset is the spec, not the code.

same .angl → new edition → 3/3 green
Examples are the tests

Generated editions never grow hand-written test suites. If a behavior matters after regeneration, it becomes an example in the chapter, and every future edition has to pass it.

untested behavior is unspecified

Read the language.

The docs cover the chapter format, the judge, fixtures, composition, compile targets, and the honest limits.