Beagle

The compiler compiles itself

The clj-target compiler is written in Beagle (self-host/). The checked-in seed is that compiler's own emitted output, and CI holds the pair to a byte-level bootstrap fixpoint (bin/beagle-remint) plus byte-agreement with the original Racket compiler, which now serves as the conformance oracle (bin/beagle-certify).

Stage0 is a native binary. The canonical self-hosted compiler ships as a self-contained GraalVM native-image (self-host/native/beagle-selfhost), built reproducibly with nix build .#beagle-selfhost. Running the seed under babashka (bb -cp self-host/seed …) is a dev convenience and the substrate for the remint fixpoint loop — the two are held byte-identical, so the native binary is the distribution artifact and bb is the fallback. Details: self-host/README.md.

How it compiles

.bclj / .bjs / .bnix / .bodin  ──▶  parse ──▶ check ──▶ emit  ──▶  .clj / .js / .nix / .odin
                                                          ▲
                                            macros, schema, stdlib, type narrowing
                                            all share one AST + diagnostic path

check is where the NixOS option schema (loaded from a cache at compile time) becomes typed context: unknown option paths fail at parse time, wrong-typed values fail at type-check time, ahead of any build. Sourcemap fidelity is preserved through every canonicalization, so diagnostics point at the author's position — not a desugared intermediate.

Getting started

Requires Racket 8.x+.

git clone https://github.com/Autonymy/beagle
cd beagle
raco pkg install --link beagle-lib/ beagle-test/ beagle/
bin/beagle test --active-only       # active tier

For a real-world .bnix corpus, clone firn — schema-typed end to end; the NixOS system builds from flake.bnix directly.

<details> <summary><b>The CLI &amp; repair loop</b></summary>

Static reference docs are intentionally thin while the surface moves — the compiler is the source of truth, fronted by one CLI:

bin/beagle doctor               # is the repair loop online and working?
bin/beagle syntax FILE          # parse check (+ --repair --emit-patch)
bin/beagle check FILE           # typed checker
bin/beagle validate [FILE...]   # parse + check + schema validation
bin/beagle build [PATH...]      # compile to target (--out DIR)
bin/beagle sig NAME FILE...     # typed signature
bin/beagle fields RECORD FILE   # record fields, types, accessors
bin/beagle callers NAME FILE... # call sites
bin/beagle expand FILE          # macro-expanded source
bin/beagle explain-type FILE    # inferred types as a view

bin/beagle help lists every command. The repair loop — a watch daemon, an on-edit syntax/type hook, and machine-applicable fixes — is where the type signal becomes applied edits; bin/beagle doctor health-checks it end to end. Deeper dev tools stay as bin/beagle-* (blame, specfix, trace, cascade).

The bin/beagle-claims / bin/beagle-roundtrip backends project Beagle source into a claim graph for Fram's Chartroom. The claim log is canonical there — the source text is a view onto the claims, not a graph derived from text after the fact.

</details>

<details> <summary><b>Project layout</b></summary>

- beagle-lib/private/parse.rkt — surface form set; the source of truth. - beagle-lib/private/check.rkt — type checker. - beagle-lib/private/emit-{clj,js,nix,odin}.rkt — live emitters; beagle-lib/private/dormant/ holds the parked ones. - beagle-lib/private/nixos-schema.rkt — the typed NixOS-option environment. - beagle-lib/private/diagnostic-kind.rkt — the cause-class? taxonomy. - beagle-test/ — tiered test suite; beagle-test/tiers.rktd is the authoritative tier classification. - CLAUDE.md — the operating discipline; its three-statement generative spec (Clojure + types / load-bearing divergence / idiomatic per target) is the canonical anchor for any surface question. - docs/ — distilled, rot-resistant artifacts: INFLUENCES.md (lineage + thesis) and the generated CHEATSHEET.md.

</details>