Hale, in text
The whole of the documentation and every article, as plain HTML. No script, no webfont, no images, no colours of ours — your browser decides how this looks. Same source as the styled site, so it does not go stale.
Hale is a compiled language. Every piece of state has one owner, and parts talk only over declared topics, so the compiler can check a program's architecture the way it checks its types. There is no garbage collector and no borrow checker.
Install
curl -fsSL https://hale-lang.org/install.sh | shDocumentation
Introduction
- Introduction — Hale is an LLVM-compiled systems and service programming language designed around hierarchical arena ownership, actor-like components (locus), typed message…
- Claims & the Law — While effect contracts verify what an individual function or locus may do, claims verify architectural invariants across an entire assembled program graph…
- Constitutions — A constitution is a reusable, named collection of architectural claims declared at the top level of a file. Constitutions allow multi-binary services and…
- DNA Architecture & Runtime Overview — In Hale, an organism combines your application with a self-governing runtime control plane (dna/org), an append-only event log and operational state store…
- Effects & Contracts — In Hale, functions and loci can declare effect contracts specifying which side effects, resource allocations, or bus publications they are permitted to…
- The Habitat Layer: Multi-Organism Infrastructure and Isolation — A habitat is the root DNA organism shipped with the Hale toolchain (spec/habitat.md). Its role is to provision, supervise, and place infrastructure…
- Package Management & `pond` Catalog — Hale's built-in standard library (std::*) covers core I/O, networking, HTTP, JSON, cryptography, logging, metrics, and the message bus. Ecosystem…
- Language & CLI Reference — This chapter provides a quick-reference cheat sheet of Hale's syntax, decorators, CLI subcommands, diagnostic formats, and links to the normative language…
- Stability & Compatibility — Hale is pre-1.0. What a release may change, and how you hear about it, is written down in STABILITY.md. In short:
- Formal Design Model (`%DESIGN v1`) — Hale operationalizes a formal recursive hypergraph model (%DESIGN v1) at the programming language substrate. Every syntactic construct and compiler…
- The Application Model — Alongside its code-generation IR (basic blocks, instructions, and registers), the Hale compiler frontend derives an ApplicationModel: a canonical relational…
- Units, End to End — Hale includes a compile-time unit, quantity, affine-point, and integer-range type system designed around a single invariant: widening is automatic and…
- Verification & Model-Checking Reference — Hale verifies programs at two levels: For the exhaustive specification of every static check, see spec/verification.md.
Basics
- Control Flow — Hale provides if/else branches, exhaustive match expressions, while loops, and for range/collection loops. Both if and match are expressions that can return…
- When a Call Can Fail — Hale handles recoverable, value-level errors through fallible(E) function signatures and mandatory or clauses at every call site. Unlike exceptions, errors…
- Your First Program — A complete Hale command-line program can be written with top-level functions and fn main(), or structured around an App locus that encapsulates…
- Functions — Functions in Hale are declared with fn, explicitly typed parameters, and an optional return type -> T. Every top-level function in a directory (seed) is…
- Math, Money & Time — Hale provides standard arithmetic and bitwise operators alongside first-class types for exact fixed-point decimals (Decimal), nanosecond time spans…
- Strings & Text — String in Hale is an immutable UTF-8 byte sequence, while Bytes holds arbitrary binary data (including null bytes). For text processing, Hale provides…
- Values & Variables — Hale is a statically typed systems language where local bindings are immutable by default and primitive types cover integers, floats, exact decimals…
Dna
- The `dna::Dna` Locus and Organization Architecture — Every DNA organism is assembled as a standard Hale program in dna/org/main.hl that instantiates the dna::Dna locus from vendor/dna. Because the entire…
- Getting Started with DNA — This guide walks through provisioning a new DNA organism, configuring its local infrastructure in the habitat, populating secret slots in the vault…
- Edge API Server, Web UI, and Reviews (The Head and the Face) — The head (dna/api) is the edge API server for a DNA project. It authenticates callers (via OIDC sessions, bearer tokens, or Unix domain sockets), resolves…
- The Heart and the Body — In DNA, the heart is your supervised Hale application, and the body is the host supervisor (dna/host running under hale dna dev or hale dna run) that holds…
- Worker Processes, Tools, and Model Routing (Legs, Hands, and Voice) — In DNA, a leg (hale dna work) is a stateless worker process that claims one task attempt from the edge API (head), reads the attempt's structured context…
- Memory and the Record — DNA persists all governance history and operational state in PostgreSQL inside a per-organism schema named dna_. Long-term governance decisions are stored…
- The Nerves — The nerves are the organism's NATS JetStream broker (nats:2), running on the private-services tier with a dedicated durable stream per organization (DNA_)…
- DNA & Habitat Reference — This reference catalogs every CLI command (hale dna, hale habitat, hale node), environment variable, Git configuration key, record/ledger row kind, hale dna…
- Recurring and Cron Schedules — A schedule binds a recurring interval (--every) or UTC cron expression (--cron) to a catalog workflow definition (--definition) and a convening position…
- Senses and Reflexes — The senses are a Prometheus metrics server (senses- in the local habitat) that scrapes /metrics endpoints exposed by long-running DNA components (spine…
- Organization Governance, Grants, and Structural Evolution — The genome is the Git-tracked source code defining both your application and its governing organization under dna/org/ (topology, constitutional law…
- The Skin — The skin is the organism's credential, identity, and failure-containment boundary (dna/host/secrets.hl, dna/core/principal.hl, dna/oidc/stub.hl). It…
- The Spine — The spine is the workflow execution engine, budget coordinator, and record projector that runs on every DNA node. It consists of the host supervisor started…
- DNA Architectural Engineering Standard — This document defines the architectural engineering standard for DNA organisms and the DNA runtime itself. While individual Hale language features…
- Operational Troubleshooting Guide — This guide indexes exact diagnostic messages printed by hale dna, hale habitat, and hale node, grouped by subsystem, along with their root cause and…
- One Task, End to End — This chapter traces a single request from terminal submission (hale dna task create) through planning, sandbox editing, toolchain verification, review…
Everyday
- CLI & config — Hale provides command-line argument and environment variable access in std::env, layered configuration resolution in std::cli::Resolver, and low-level…
- Lists & Maps — Hale does not use garbage-collected generic container values like Vec or HashMap. Instead, dynamic collections are loci annotated with @form(...) whose…
- Hashing, encoding & randomness — Hale provides cryptographic digests, HMAC authentication, digital signatures (ECDSA P-256, RSA-PSS, Ed25519 and secp256k1), hex and Base64 codecs, and…
- Files — Filesystem operations in Hale live under std::io::fs (whole-file reads, writes, and directory operations) and std::io::file (streaming file handles). Every…
- Generics — A type, a locus or a fn can take type parameters in angle brackets, so one declaration serves several types. Each use names its types (Envelope), and the…
- HTTP — std::http provides an HTTP/1.1 server, request router, streaming SSE and chunked-body writers/readers, and an outbound HTTP/HTTPS client. An HTTP server is…
- JSON — Hale provides two ways to work with JSON: compile-time generated struct codecs (Type::from_json and Type::to_json) for fixed schemas, and the std::json…
- The Locus, Gently — A locus is Hale's primary structural building block, combining state (params), behavior (fn methods), and lifecycle management (birth, run, dissolve) into a…
- Logging — std::log is a publish/subscribe logging system built on Hale's typed message bus. A Logger publishes LogEvent records to topic log., and one or more sinks…
- Metrics — std::metrics provides Prometheus-compatible counters, gauges, and histograms backed by a thread-safe Registry. Register metric handles at startup, update…
- Observing a program — Hale programs expose four observability surfaces: structured application and runtime logs, Prometheus metrics (std::observe::Scrape), HTTP health and…
- Records & Data — Hale models structured data with nominal type records, tagged enum unions, and type-tagged set unions (A | B | C). Every data type is checked at compile…
- UDP & TLS — Below std::http, Hale provides low-level socket primitives in std::io::udp, std::io::tls, std::io::tcp, and std::io::sockopt. These modules wrap platform…
- Testing — A test in Hale is an ordinary standalone .hl file named _test.hl whose fn main() runs assertions from std::test. hale test discovers all _test.hl files…
Getting started
- Quickstart & Toolchain — Create hello.hl: Compile and execute it in one step with hale run: To produce a standalone native binary on disk, use hale build:
- Install — You can install hale using a prebuilt release archive (fastest) or by building from source. Because hale compiles programs to native machine code and links…
Parts
- Part VI: Multi-Record Control Plane (Habitat) — While a single DNA organism manages one application and its PostgreSQL/Git record, Habitat (hale habitat) is the control plane for provisioning, isolating…
- Part I: Language & Standard Library — Part I covers Hale's core syntax, type system, error handling, data structures, and built-in standard library (std::*). Everything in this part works in…
- Part II: Concurrency, Services & APIs — Part II covers building concurrent, long-running services, API servers, and multi-binary distributed systems using the locus model.
- Part V: DNA (Autonomous & Governed Applications) — Part V covers DNA (vendor/dna and hale dna), Hale's framework and runtime for building self-governing, auditable software systems where human operators and…
- Part IV: Systems Programming & Runtime Internals — Part IV covers low-level memory management, zero-allocation hot paths, lock-free shared-memory messaging, C and WebAssembly interoperability, and runtime…
- Part III: Static Verification & Architecture Laws — Because hale check derives a complete, canonical graph of your program—every locus, ownership edge, bus publish/subscribe edge, function call, and side…
Services
- The API Surface — Hale programs declare their external RPC and streaming interfaces as API surfaces (api blocks and @rpc annotations). From a surface declaration, the…
- Designing API Messages — An API surface's wire contract is determined directly by the Hale types used in its rpc rows. By choosing specific record field patterns, enum shapes, and…
- Build an API — In Hale, you expose a service's methods as an external API by declaring an api surface and binding it to a transport with api::serve. The compiler generates…
- The Bus — The Hale bus provides typed, many-to-many message passing between loci without shared pointers or channel plumbing. Loci declare which topics they publish…
- Concurrency & Placement — In Hale, every locus is single-threaded internally, and concurrency is configured declaratively on the main locus via a placement { } block. You write…
- Failure & Supervision — Hale separates recoverable call errors from supervisor-level component failures into two distinct channels: the value channel (fallible(E) and or) and the…
- Locus Lifecycle — A long-running locus executes through a deterministic sequence of runtime-managed phases: birth → run → drain → dissolve. Instead of threading cancellation…
- Multi-Binary Deployment & Fleets — In Hale, splitting a single-binary program into multiple communicating services requires zero changes to publisher or subscriber code. By adding a bindings…
- Parents & Children — Hale organizes loci into a strict parent-child ownership hierarchy where every child's memory region is nested inside its parent's arena. Parents can hold…
- Composition Patterns — This catalog documents the standard multi-locus architectural patterns used in production Hale services. Rather than storing loci inside hash maps…
- Perspectives — A perspective is a program-wide, live-rebindable contract slot. Loci program against the contract's method signatures and bus subscriptions through…
- Repositories — A repository is a locus annotated with @repo(T) that manages authoritative domain records of type T (backed by in-memory storage, SQL, or files). Marking a…
- Seams — A seam is a declarative pipeline inside a locus: a chain of hops, each taking what the one before it produces. A hop is one method, or a whole locus: when a…
Spec
- The API surface — A program exposes an operation by saying so in a row: a surface is a named table of operations (rpcs), each row naming a handler and the roles a caller must…
- Design decisions (the F-series) — An append-only log of Hale's locked design commitments — one record per major decision. Each F.N is a stable navigation tag, referenced from code comments…
- Design rationale — For each major syntactic construct in the Hale grammar, this document records: evidence that constrains the design.)
- DNA — DNA is the part of a Hale application that governs how the application changes. It ships as a library inside the toolchain (vendor/dna, the dna/core seed of…
- spec/ffi.md — Foreign-function interface (`@ffi("c")`) — User-extensible bindings to external C-ABI libraries. Library authors declare extern symbols in .hl source via an @ffi("c") annotation; the compiler emits…
- Forms — A form is a compiler-recognized annotation on a locus declaration that picks an efficient lowering for the locus's storage and synthesizes a standard method…
- Codename legend — The spec and code comments carry a few families of short internal tags from Hale's development history. Most are navigation breadcrumbs, not part of the…
- The habitat — This document specifies the habitat as shipped (GH #1653). It describes the local profile, the only one built; the hosted profile is not. The organism it…
- Memory model — This document specifies Hale's memory model: how regions are allocated, organized, and freed; how locus structure constrains memory layout; how access…
- The canonical semantic model — The typed intermediate representation every structural consumer reads. GH #476 built it; this document is its contract.
- Package management — Hale's v1 package-management surface is small and explicitly git-based. A project declares its direct dependencies in hale.toml; running hale fetch clones…
- Operator precedence and associativity — Operators are listed from highest precedence (binds tightest) to lowest (binds loosest). Operators on the same row have the same precedence; their…
- Projects — A Hale project is a directory tree of .hl source files plus anything those files vendor or reference. This document covers the on-disk shape: how the…
- The graph registry — GENERATED from crates/hale-graph/src/registry.rs and held byte-equal by registry_matches_spec. Do not edit: change the table and run HALE_REGEN_REGISTRY=1…
- Runtime — What every compiled Hale binary always ships with. Always- loaded; not optional; no import needed; the substrate every Hale program depends on.
- Operational semantics — This document specifies what Hale programs do when they run. Where grammar.ebnf says what's syntactically valid and types.md says what's meaningfully valid…
- Standard library — Bundled with the toolchain, no separate install required. This document describes the current stdlib surface. Milestone / phase history lives in…
- Style guide — This document specifies idiomatic Hale in four layers: the shapes a program is composed of, the correctness rules that keep a long-lived program sound, the…
- Testing pipeline — The testing pipeline is part of the language toolchain, not an add-on. hale test ships in the same binary as hale build. Test infrastructure exists from day…
- Lexical structure — This document specifies the lexical layer of Hale: the set of tokens the lexer produces and feeds to the parser. The formal grammar in grammar.ebnf is…
- Type system — This document specifies Hale's type system: what types exist, how they relate, what the compiler verifies. Where the grammar (grammar.ebnf) tells you what's…
- The unit dialect — A program says what its integers count. It declares units and the equations between them, and scalar types counted in them: a quantity (an amount: Money…
- Static verification surface — This page is the canonical catalog of the compile-time checks the toolchain runs beyond ordinary type-checking — the structural and semantic guarantees a…
Systems
- Binding C Libraries (`@ffi("c")`) — Hale binds external C libraries directly through @ffi("c") function declarations, a small C glue file when needed, and linker flags in hale.toml or on the…
- Forms Under the Hood — A @form(...) annotation on a locus instructs the compiler to lower a capacity slot (heap or pool) into a monomorphized, type-specialized data structure and…
- Iris: Live System Observer — Iris is Hale's built-in live topology and telemetry observer. When a Hale binary runs with LOTUS_OBS=1 (or via hale run --observe), Iris attaches to its…
- Memory & Lifetime — Hale manages memory through hierarchical region allocation rather than garbage collection or compile-time borrow checking. Every locus owns an arena…
- Execution Modes (`bulk`, `harmonic`, `resolution`) — A locus can declare up to three named execution modes—bulk, harmonic, and resolution—to express distinct hardware execution strategies (vectorized batch…
- Operations & Production Debugging — Hale binaries include built-in, zero-overhead hooks for diagnosing message drops, tracking arena memory residency, supervising OS subprocesses, and…
- Performance & Zero-Allocation Hot Paths — Hale bounds most memory growth automatically through per-method scratch regions and whole-field replacement retirement. For latency-critical or…
- Deterministic Record & Replay — Hale's flight recorder (LOTUS_OBS_RECORD) captures a program's message delivery schedule, wire ingress payloads, and non-deterministic standard library…
- WebAssembly & the Browser — Hale compiles directly to a self-contained .wasm module and an ES module loader (.mjs) without requiring Emscripten, wasi-sdk, or external bundlers. The…
- Zero-Copy & High-Frequency Bus — For high-throughput, same-machine message routes (100k+ messages/sec), copying payloads across locus boundaries can dominate latency. Binding a topic to…
Tutorial
- Tutorial: Build a Job Queue — This tutorial walks through building a job queue in four stages—starting from a 12-line script and evolving it into a multi-process service—while keeping…
Articles
- what the hale!? — 2 September 2026. Why build a new language in 2026. A locus owns state and talks over declared topics, and that one restriction turns out to carry most of what code review was for: the architecture stops living in docs and heads and becomes the only sentence the language accepts — from a value, to a binary, to a fleet.
- Record & Replay — 13 August 2026. Record one concurrent execution, then re-run the same program with the same journaled inputs and the same per-consumer delivery order. How Hale turns its typed bus, effect frontier, and runtime ownership of scheduling into a replayable incident — without asking application code to instrument itself.
- Secrets — 8 August 2026. A signing key the rest of the program cannot reach, using the ownership model that was already there. One annotation closes the gap in it, one built-in effect class marks the privileged operation, and the law is written with the claim forms the language already has.
- Fleets — 6 August 2026. Claims close one application; a fleet plan closes one deployment of many. Topology artifacts compose across binaries, cross-process law gets checked with cross-process witnesses, and signatures carry the certificate to the machine that runs it. What a development lifecycle looks like when every stage from function to fleet is either proven or refused.
- Constitutions — 5 August 2026. Claims stay closed-world, but their source no longer has to be copied into every main locus. Constitutions share one claimset across entrypoints and environments, compose only by addition, and make missing coverage an error.
- Claims — 4 August 2026. Write the system's laws before finishing its implementation, then let the compiler drive the program toward them. Named claims over Hale's call, message, effect, and topology graphs turn isolation, required wiring, single-writer rules, capability boundaries, and quantitative limits into ordinary development feedback.
- Effects — 31 July 2026. A function can declare what it is allowed to reach, and the compiler proves the claim over the entire call graph. Effect classes, quantitative budgets, per-phase contracts, causal tracking in both directions across the bus, and effect classes a program declares for itself.
Elsewhere
- Source, on GitHub
- The styled site, which has a playground and diagrams
- llms.txt