Skip to content
This repository was archived by the owner on Oct 14, 2026. It is now read-only.

v0.20.0

Choose a tag to compare

@tompassarelli tompassarelli released this 07 Aug 04:17

Beagle v0.20.0

Highlights

  • Native Core is now the center of the language: .bgl with bare #lang beagle always targets Native Core and lowers source stage → typed stage → frozen native program, with the materializer (restricted C17 or QBE) selected at build time rather than baked into the source. Roughly half the release's commits expand lowering coverage, and 31 committed validation drives execute real fram modules — fold, types, store, rt-core, kernel classify, FRI replay — end-to-end through C17 to running executables.
  • The world ontology is retired. The native-core stage schema is now stages.bclj with NativeCoreProgram and Frozen*StageV0 records, the build artifact is module.native-program with program-* report keys, content-digest is a real sha256 over an extended canonical encoding, and the dead draft/freeze/promote/Artifact lifecycle is deleted outright.
  • The typed-binding surface is locked: flat name: Type is the only annotation spelling at every binding position, returns are -> Ret, and the parenthesized and bracketed spellings are hard parse errors with pointed fix-its. Typed destructuring is gone (bind a name, destructure in the body), a binding vector annotates every binding or none, and roughly 6,200 annotation sites were recanonicalized in-tree. Both the Racket and self-hosted compilers close the grammar identically.
  • The checker now narrows on runtime proofs: a match arm refines a stable scrutinee to the matched member, and (instance? Member x) intersects on the true branch and subtracts from closed unions on the false branch — clearing 62 of 82 reported errors on native-core's own check profile without touching its source.
  • QBE landed as the first direct-native materializer and the anti-C-capture check: it reads the same frozen program C17 reads, and every QBE-shaped concession stays inside the materializer. Target ABIs became named inputs — layout measurement takes an ABI profile, QBE refuses a non-lp64 program by name, receipts attest the profile, and a gated wasm32 drive compiles and runs slices under the wasi clang and wasmtime against a committed seam ledger.
  • The ScriptC, Odin, and Zig targets were removed; the semantic-contract work from that arc (typed error carriers, composable allocation/domain raise sets) survives target-neutrally in the checker, and the native strategy consolidates on the C17 and QBE materializers.

Language

  • One annotation grammar: flat name: Type at every binding position — fn/defn/letfn/method params, defrecord and defunion fields, def/defonce, let/loop/with-open/if-let, define-macro contracts — with -> Ret returns. Wrapped (x : Int), [x : Int], and annotated-pattern spellings are rejected with fix-its that name the flat form; a mixed typed/bare binding vector is a parse error naming the offending binding (& rest exempt, x: Any satisfies the rule); a capitalized bare binding draws a lint since it usually is a dropped annotation.
  • match and instance? narrowing follows the ratified rules: arm-local refinement of stable lexical scrutinees, parametric scrutinees keep their substitutions through a member view, set! and ^:dynamic disable narrowing, and the false branch of instance? removes the member from a closed union.
  • Variant patterns bind the field (not the variant), variant accessors are emitted, and both behaviors were ported to the JS target.
  • A required module's defunion registers its whole variant surface, and imported defalias definitions expand through the provider require graph, so cross-module unions and aliases resolve the way same-module ones do.
  • Typed error contracts are modeled in the checker with payload carriers, allocation and domain raise sets compose, and an allocating function must declare :raises AllocationError.
  • Checker precision fixes: closed dynamic map keys are permitted, regex proofs survive Any bindings, record constructors are identified by registry rather than name shape, declared types are enforced through with-open and for :let bindings, and duplicate-namespace ambiguity is deferred instead of eagerly fatal.
  • Purity refinements: a self-opened transient counts as local mutation rather than a leak (in both the check and derivation passes), and loop bindings are walked when collecting mutation markers. Error values preserve namespaced payload keys.

Native Core

  • The staged pipeline is complete and first-class: stage schemas with canonical encodings and receipts, a determinism gate, a complete-module compilation command, and linking of complete modules into executables. All seven obligations — SSA, exhaustive match, closed layouts, checked arithmetic, legal ABI, token discharge, bounded effects — are validated with committed rejection fixtures and a rejection-depth corpus, so the pipeline provably refuses what it must.
  • Lowering coverage grew across the core vocabulary: loop/recur as SSA header blocks with back-edge jumps, checked integer arithmetic and division through the Outcome protocol, closed Atom mutation/assoc/compare-and-set, closed and dynamic keyword access, the Vec vocabulary (header-reference layout, count/nth/conj, literals, sequence primitives, doseq), persistent map and set operations, reduce-kv over closed maps, transients, exact float arithmetic and parse-double, deterministic stringification, sealed structural equality for dynamic values, and exhaustive sealed matches.
  • Union machinery deepened: records narrow through nested unions, a closed union narrows into a sub-union as a checked extract, flow arms join on the declared type when they cannot join structurally, carried nil alternatives widen, and map absence aligns with source optional unions.
  • Capability ABIs landed for stdout, host environment, sockets, and a monotonic clock, alongside sha256 byte-digest and codec source primitives, an explicit Atom state seam, growable arena materialization, and a write-capability arena acquire that satisfies bounded-effects with the write effect settled up the call graph. Function-bearing ABIs are refused.
  • Exact Unicode 15 text semantics matching JDK21 are embedded behind a gate, so native text operations agree with the hosted target's observable behavior.
  • The QBE materializer emits .ssa from the same frozen program as C17 — block parameters lower to phi nodes, explicit-offset aggregates are cross-checked against QBE's own layout computation rather than weakened to it — and its drive compares two independent emissions byte-for-byte. QBE is provided in the dev shell.
  • ABI profiles are explicit end to end: layout measurement takes the target ABI as a named input, build entry points and validation drivers thread NATIVE_SLICE_ABI, closed-layouts attests the declared profile, receipts name it, and the wasm32 validation drive (gated on BEAGLE_WASI=1) compiles slices with the wasi clang at -std=c17 -pedantic -Werror, runs them under wasmtime, and fails on seam growth or emission drift against a committed ledger.
  • A trapped instance now tells its host why it died: the trap code is recorded and reported through an optional, non-recursing reporter before abort — report only, a trap still aborts.
  • Cross-repo fram drives fail loudly on absent fram source, module identity resolves from the source-stage module table and survives lowering, and the drives track fram's live layout (t1/t2/t3 vocabulary, renamed sources, re-vendored fram-resolve corpus).

Self-host & remint

  • The facts-roundtrip core was ported to the self-hosted compiler, exposed on the CLI, and certified against an oracle corpus, with reader edge semantics and cached source locations brought into agreement.
  • Remint divergences were repaired for the JVM instance-position checker (receiver-adjusted arity, locked direction) and the graph emitter (expression-valued call heads, mint render round trips).
  • The self-hosted parser gained Nix inherit map entries and throwable unions, and emit-clj escapes control characters the Clojure reader accepts.
  • The self-host exemption ledger is truthful: explicitly unsupported forms are classified as unported rather than silently exempted.
  • The self-hosted compiler enforces the locked binding surface identically to the Racket compiler — the same three wrapped-form rejections, mixed-vector rejection, and the capitalized-bare warning — and the seed was reminted accordingly ([x : Int] previously miscompiled there into a binding literally named #%:).

Tooling & CI

  • Stale Racket bytecode is structurally impossible at the entrypoint seam: the one sourced entry file gates on a content-addressed stamp and runs raco make -j over every tracked .rkt when anything is newer or the pinned racket changed, with flock serialization for concurrent entrypoints and a BEAGLE_NO_ZO_GATE=1 escape. Bytecode also auto-recompiles when the pinned racket itself changes.
  • A canonical signature formatter lives outside the parser and is exposed as a command; two-entry signatures stay compact, nested signatures converge, and the authored and test corpora were reflowed at the flat canonical width.
  • Beagle source is text-authoritative: graph-registry adoption and @upstream:graph markers are gone, and native-core modules were de-adopted from graph upstream — graph projection remains a read-only view, never a gate.
  • Targets live in one canonical table and every target list in docs and tooling is a rendered view of it, so target inventories cannot drift.
  • CI pins Fram release compatibility, explicit Fram resolver output is honored, and secret scanning no longer misreads Beagle type annotations as credentials.
  • Firn gained a deterministic semantic index v1 with recovered authored option spans; beagle doctor probes the daemon endpoint directly; the Nix importer's parser recovers physical source locations from Nix tokens.
  • JS target: typed module boundaries are executable, and let initializers are scanned for local mutation.

Breaking changes

  • The typed-binding surface is locked to flat name: Type. The parenthesized (name : Type), bracketed [name : Type], and annotated-destructuring ([a b] : Type) / ({:keys [...]} : Type) spellings are hard parse errors with fix-its pointing at the flat form. Typed destructuring is removed entirely — bind a name and destructure in the body. A binding vector must annotate every binding or none, and the formatter emits only the flat spelling. Both compilers reject identically; existing sources need the recanonicalization the in-tree corpus received.
  • The world ontology is retired across the pipeline. In native-core, worlds.bclj became stages.bclj, NativeWorld became NativeCoreProgram, stage records are Frozen*StageV0, the build artifact is module.native-program (plus .sha256), report keys are program-*, and content-digest is now a real sha256 over an extended canonical encoding — previously digested material changed shape, so stored digests do not carry forward. The draft/freeze/promote/Artifact lifecycle is deleted. In the hosted checker, world-check became module-overlay-check and its receipt key is overlayDigest; the ownership/world-tick convention is deleted.
  • The ScriptC, Odin, and Zig targets are removed from the compiler, self-host, tooling, and target tables. Projects on those targets must move to a supported target; the native path is the C17 and QBE materializers.
  • .bgl with bare #lang beagle is exclusively Native Core: it lowers to an immutable validated native program with the materializer chosen at build time. Hosted-dialect sources use their target extensions (e.g. .bclj); in-tree non-core .bgl files were renamed accordingly.