ferrule language specification

this is the specification for ferrule α1. it describes what the language is and what it will be. each document has front matter that tells you what's implemented, what's planned, and what's been deferred to future versions.

the spec is the single source of truth. if something isn't in here, it's not part of the language yet.

how to read this

each document has yaml front matter at the top:

---
title: some feature
status: α1          # α1, α2, β, or rfc
implemented:        # sections that work right now
  - basic-stuff
  - other-thing
pending:            # sections planned for this phase
  - advanced-stuff
deferred:           # pushed to later phase or rfc
  - complex-thing
---

status meanings:

• α1 means it's part of the current milestone
• α2 means next milestone
• β means later
• rfc means it's a proposal, not committed

conventions:

• code for syntax and identifiers
• [link](path) references the canonical definition
• examples are runnable unless marked otherwise

design pillars

these are the five ideas that guide every decision:

1. regions are the memory model: every allocation lives in a region, no gc, no borrow checker. you choose the region, the compiler enforces lifetimes.
2. effects are the control flow model: errors, async, generators, resource cleanup all unified under one mechanism. fail<E> is just an effect. suspend is just an effect. no special syntax for any of them.
3. capabilities are the authority model: no ambient access, everything is passed. fs, net, clock, rng are values. the runtime is a record type that provides them.
4. types carry meaning: nominal types, refinement types, effect-aware function types. two records with the same shape are not the same type. a Port is not a u16.
5. no magic: one way to do each thing, explicit over implicit, weakest mechanism that works. no macros. no implicit coercions. no hidden control flow.

what's in α1

the core language that you can actually use:

what's deferred

these features are designed but not part of α1:

looking for future features? check out the rfcs for proposed additions to the language.

specification index

core language

functions and effects

error handling

memory model

modules and capabilities

unsafe

concurrency (β)

advanced (α2+)

reference

key decisions

these are the choices that define ferrule:

to be defined

these decisions are still open:

language identity

ferrule is a systems language where regions, effects, and capabilities are first-class. you get low-level control with safety guarantees about what code can do, what memory it touches, and where allocations live, without a gc or a borrow checker.

target users:

• embedded developers who want more safety than c
• server developers who want more control than go
• security-critical systems where capability audit trails matter
• developers who want rust-style safety without fighting the borrow checker

what it's not:

• not rust (no borrow checker, regions instead, simpler generics)
• not zig (effects and capabilities are language features, not conventions)
• not go (no gc, explicit error handling, no ambient authority)