
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
Louise v0 — Language & Compiler Plan
v0 is done (issue #13). What it deferred is planned in the v1 roadmap.
Revised 2026-10-09 by the project owner. Revision 1 of ADRs 0001–0004 changes these items:
Refis scoped to regions;sendmoves, shares or copies;ctlcompiles natively by stack switching;- unwinding is zero-overhead and table-driven;
- tail calls are guaranteed, including tail recursion modulo cons;
- the scheduler is multi-threaded from day one;
- Rust-style
@testand an extended@derive.Where this plan and the ADRs differ, the ADRs win.
Approved 2026-10-08. Decisions are detailed in docs/adr/ and runtime-abi.md; where they differ, the ADRs win.
Context
Louise is a new programming language. The repository is empty: one commit with a blank README. The goal is a statically typed, effectful language built from:
- Koka: algebraic effects, row-polymorphic effect types, and Perceus RC (no GC).
- OTP: actors, links, monitors, supervisors and "let it crash".
- Gleam:
use x <- f(..)callback sugar,@externFFI and typed subjects. - JSX: inline HTML literals.
The compiler, the runtime and the LSP are all written in Rust.
v0 definition of done: a supervised HTTP server that:
- renders SSR HTML literals,
- hashes passwords with argon2 linked in over C FFI,
- uses effect handlers for logging and for a mockable DB,
- is edited in VS Code with a working LSP (diagnostics, hover with types and effects, go-to-definition).
Decisions locked with the user:
- Perceus RC with inferred borrows, one-shot resumptions and no tracing GC.
- Emit C, and link a Rust runtime staticlib.
- HTML: SSR first, typed so a client target can be added later.
- Types: HM, row effects, ADTs, nominal records and single-parameter traits. No HKT.
- Syntax: braces, Gleam/Rust-like.
An independent architecture review was folded in. Its corrections are marked ⚠.
Per Innoptech policy, the architecture ADRs (runtime ABI, effect lowering, memory model, actor model) are reviewed by the engineering team before M5 starts.
1. Language surface (v0)
import std/actor.{type Subject}
import std/io
pub type User { User(name: String, email: String) }
effect log
{
fn log :: msg: String -> () // tail-resumptive: no capture
}
effect fail
{
final ctl fail :: reason: String -> Never // never resumes (exceptions)
}
pub fn greet :: u: User -> Html / <log>
{
log ("rendering " <> u.name)
<div class="card"><h1>{text u.name}</h1></div>
}
pub fn main :: -> () / <io, proc>
{
use <- with_console_log // Gleam `use` == Koka `with`
let page = greet User("Ada", "ada@x.io")
io.println (html.render page)
}
fn with_console_log :: action: fn() -> a / <log | e> -> a / <io | e>
{
handle
{
action ()
}
with
{ log msg -> io.println msg // `fn` op: resume is implicit
}
}
Naming:
- Types are Uppercase (
Int,List<a>); type variables are lowercase. - Generic brackets
<>appear only in type positions, with no turbofish. That makes<at the start of an expression unambiguous, so it always opens HTML.
Functions and effects:
- Effect rows:
-> T / <e1, e2 | r>. If the row is omitted, the function is total (pure). - ⚠
pub fnrequires a full signature, including the effect row. Local and private functions are inferred. - Panics are not tracked. A failed match, Int overflow or explicit
panicunwinds and crashes the actor (OTP style).
use: desugars exactly as in Gleam. use a, b <- f(x) turns the rest of the block into f(x, fn(a, b) { rest }).
Traits:
trait Show<a> { fn show(x: a) -> String },impl Show<Int> {..},where Show<a>.- Built-in
@derive(Eq, Show, Hash). - ⚠ Method signatures declare their full effect rows, and impls may not add effects.
- ⚠ Coherence: an impl must live in the module of either the trait or the type.
Mutable refs: ⚠ Ref.new, get and set carry an <st> effect. This keeps let-generalization sound.
Int: ⚠ 63-bit tagged. Overflow panics; this is fixed in the ABI. Promotion to bigint is deferred.
Modules: one module per file, pub visibility, import a/b.{x, type T}. Packages use louise.toml. v0 dependencies are path or git only, with no registry.
2. Repository layout (Cargo workspace)
crates/
louise_span file DB, spans, stable item IDs
louise_diag diagnostics (ariadne), codes, LSP conversion
louise_syntax hand-written mode-aware lexer (+HTML), recursive-descent/Pratt parser, rowan lossless CST, typed AST views
louise_hir name resolution, module graph, desugar (use, html, pipes `|>`, records)
louise_types inference, effect rows, traits, exhaustiveness
louise_core typed ANF Core IR + effect lowering (louise_interp: the reference interpreter)
louise_perceus borrow inference, dup/drop insertion, reuse analysis
louise_codegen_c Core → C (+ #line directives)
louise_driver pipeline, louise.toml, native deps, invokes cc / cargo / pkg-config
louise_lsp tower-lsp-server frontend over the query layer
louise CLI: new | check | build | run | test | fmt | lsp
runtime/
louise_rt Rust staticlib, C ABI: ctx, objects, RC, alloc, strings/bytes, fibers, scheduler, mailboxes, reactor, timers
louise-ffi Rust helper crate exposing C-ABI types for native Rust deps
std/ stdlib in Louise: core, list, option, result, string, bytes, dict, io, actor, supervisor, html, net, http, test
editors/vscode/ TextMate grammar (with embedded HTML) + LSP client
docs/ reference/ (language reference), adr/ (decisions), runtime-abi.md
tests/ ui/ (diagnostics), run/ (stdout), snapshots (insta)
examples/http_demo/
3. Key designs
3.1 Front end (LSP-ready from day one)
Lexer:
- Hand-written and mode-aware, driven by the parser. (M1: replaces the planned logos, because HTML needs parser-selected modes; one dependency fewer.)
- Inside an HTML literal the lexer switches mode: text, tags, attributes, and
{back to expression mode, tracked with a mode stack.
Parser:
- Hand-written and error-tolerant: recovery sets per construct, with every token kept in the rowan CST.
- Both the formatter and the LSP read from this CST.
Type checker:
- ⚠ Error-tolerant from the start.
Ty::Errorsilences follow-on errors, and inference continues per item.
Incremental model:
- ⚠ Decide before M2: per-item queries keyed by stable item IDs, behind a
Dbtrait. - Start with simple per-file memoization and migrate to salsa if it becomes needed.
- Required
pubsignatures let a module's interface hash stay stable while function bodies are edited.
3.2 Types
Inference engine:
- Bidirectional HM with level-based generalization and union-find.
- Effect rows use Koka scoped labels: duplicate labels are allowed. (Handlers became lexically scoped in ADR 0010, so there is no
mask.) - ⚠ Generalize a
letonly when its effect is total.
Traits:
- Single-parameter traits, elaborated to dictionary passing in Core.
Pattern matching:
- Maranget usefulness and exhaustiveness checking, which also reports redundant arms.
Records:
- Nominal records (field access, update syntax). No row-polymorphic records in v0.
3.3 Effect lowering (native backend)
| Op kind | v0 native strategy |
|---|---|
fn (tail-resumptive) | Evidence passing: direct call to the clause. ⚠ The clause runs with the evidence vector from where the handler was installed, not from where the op was performed. |
final ctl (never resumes) | Yield-bubbling unwind, lowered explicitly in Core before Perceus (let x = f(..); if yielding(ctx) return), so Perceus inserts the drops on that path. |
general ctl (captures resume) | ⚠ Interpreter only in v0. Codegen rejects it with a clear diagnostic. The demo doesn't need it. |
- ⚠ Where yield checks go: after every call, except to a callee proven never to yield. This was corrected by the M0 spike: panics and kills unwind through any frame (see ADR 0003).
- ⚠ Ownership of op values: op arguments and resume values are always owned, never borrowed.
- ⚠ Explicit context:
- Every generated function takes
tl_ctx* ctxfirst: yielding flag, evidence vector, reduction counter, current actor. - Thread-locals are never used for this state.
- Every generated function takes
- ⚠ Tail calls:
- Self tail calls compile to
goto. - Other tail calls use
__attribute__((musttail))where supported (clang, GCC 15+). - OTP
loop(state)must run in constant stack.
- Self tail calls compile to
The general-ctl path in v1 will extend the same yield-bubbling scheme (as Koka does). That keeps a later wasm/JS client target possible, since those have no fibers.
3.4 Memory (Perceus)
Value representation:
- A uniform word: a tagged 63-bit int, or a pointer to an object.
- ⚠ Self-describing header: rc (int32, negative means shared/atomic), tag, scan_fsize, plus a raw-bytes count and a pinned bit.
RC insertion:
- Core → borrow inference → dup/drop insertion → reuse analysis (FBIP) → drop specialization.
- ⚠
dropis iterative (delayed free list), so freeing a long list cannot overflow a small fiber stack.
Allocator:
- ⚠ Global mimalloc behind
tl_alloc(ctx, size). - Debug builds count live objects and bytes per actor. The test harness asserts zero live objects at exit.
Actor death:
- Cancel-unwinding the actor's stack runs every drop. The same path serves panics and linked exits.
- Cycles through mutable refs can leak. This is a documented v0 limitation.
3.5 Actors / OTP (runtime in louise_rt)
Scheduler:
- N scheduler threads, one per core.
- ⚠ v0 pins each actor to a thread at spawn (round-robin), with no work stealing. That avoids TLS and
!Sendhazards; stealing is v1.
Fibers and preemption:
- Each actor runs on its own fiber: mmap'd stack with a guard page, switched with corosensei or a small asm switch. The M0 spike decides which.
- The compiler inserts reduction-count checks at function entry and loop back-edges. When the count is exhausted, the actor yields to the scheduler.
Process ops:
- Process operations form a built-in effect
<proc>:spawn,send,receive,self,link,monitor,exit,trap_exits. - Tests use real actors as fakes, with virtual time; a handler of
<proc>is possible but not a practical mock (ADR 0004, note of 2026-10-12).
Typed mailboxes:
- ⚠
Subject<msg>(pid + unique tag) andSelectorfor typed selective receive withaftertimeouts, as in Gleam OTP. - This lets
callreplies, monitor DOWN messages and timer ticks each have their own types.
Sending messages:
senddeep-copies the value into the receiver.- ⚠ The copy keeps a forwarding table so structure shared inside the message stays shared.
- Closures copy correctly because the code pointer is a raw field and the environment is scanned.
- Large
Bytesand thread-safe Resources are shared with atomic RC instead of copied.
Send safety:
- ⚠ A static
Sendauto-trait is checked onSubjectmessage types. - At runtime, a pinned header bit (non-thread-safe Resources) makes the deep copy fail. The sender then crashes with a clear reason.
Standard library (written in Louise):
actor.startis a gen_server-like abstraction with typedcallandcast.supervisorprovides one_for_one, one_for_all and rest_for_one, with restart intensity.
IO, timers and blocking calls:
- IO uses a mio reactor; actors park on fd readiness. Timers come from a timer wheel.
- FFI marked
blockingruns on a single "dirty" thread pool in v0. The actor parks meanwhile, and ⚠ a kill is deferred until the call returns.
3.6 Inline HTML
Representation:
- Literals desugar to a typed
Element<msg>ADT, withtype Html = Element<Never>. - Variants: element, text, fragment, raw.
Typing rules:
- ⚠ A child
{e}must beElement<msg>orList<Element<msg>>, unified with the parent'smsg. - Text goes through an explicit
text(x)call, using aToTexttrait. - Attribute values use
ToAttr.on*attributes are typed specially; they're reserved for the client target.
Components:
- An Uppercase or dotted tag calls a function with labelled props plus
children.
Rendering:
html.renderescapes by default and writes to a rope/iolist (Bytesbuilder), never by repeated string concatenation.
3.7 FFI and native dependencies
Declaring externs:
@extern c "argon2id_hash_encoded" blocking
fn argon2_hash ::
pw: String
salt: Bytes
t: Int
m: Int
p: Int
-> Result<String, Int> / <ffi>
- Allowed types:
- Int, Float, Bool.
- String and Bytes, passed borrowed as ptr+len.
- Owned returns built through
tl_bytes_alloc/tl_string_alloc. Resource<t>, an opaque handle with a finalizer, markedthread_safeor not.
- The effect row is mandatory and defaults to
<ffi>. - ⚠
@externitself is built in M5, because std IO and strings call intolouise_rt.
Native deps in louise.toml (M7):
[native.argon2]
kind = "c" # c | static | pkg-config | cargo
sources = ["vendor/argon2/src/*.c"]
include = ["vendor/argon2/include"]
kind = "cargo"builds astaticlibcrate that exportsextern "C"functions using thelouise-ffitypes. This is the path for Rust libraries.
3.8 LSP and tooling
Server:
- tower-lsp-server over the query layer.
Features:
- v0: diagnostics, hover (type + effect row), go-to-definition, document symbols, and completion of module members and locals.
- Code action: "insert inferred signature" for
pub fn. - Stretch: inlay hints for inferred effects.
VS Code extension:
- A TextMate grammar with embedded HTML, plus an LSP client launching
louise lsp.
Other tooling:
louise fmtformats from the CST; this is the last item in v0.louise testrunstest fns fromstd/test.
4. Milestones (each ends with something runnable)
| # | Milestone | Exit criteria |
|---|---|---|
| M0 | Foundations | Workspace, CI (fmt, clippy, test). ADRs: syntax, memory model, effect lowering, actor model, FFI. ⚠ docs/runtime-abi.md (header, tl_ctx, calling convention, unwind protocol, FFI types). ⚠ Hand-written C spike against louise_rt: RC objects, fiber switch, preemption, cancel-unwind, leak counter at 0. Engineering-team review of the ADRs. |
| M1 | Syntax | Lexer with HTML mode, error-tolerant parser, rowan CST, insta snapshots, a fuzz test with no panics, louise check reporting parse errors. |
| M2 | Names + core types | Resolution, modules and imports; HM, ADTs, records, match plus exhaustiveness; traits and derive; use desugar; error-tolerant checker; tests/ui harness. ⚠ Diagnostics-only LSP ships here. |
| M3 | Effects in types | effect declarations, row inference, handle/with, mask, total-only generalization, <st> refs. LSP hover shows effects. |
| M4 | Core + interpreter | Lowering to typed ANF Core; the reference interpreter runs everything, including general ctl. louise run --interp gives the first programs running. |
| M5 | Native backend | Effect lowering pass (yield checks before Perceus), Perceus, C codegen, louise_rt objects, strings and bytes, @extern to louise_rt, #line, self tail calls to goto plus musttail. tests/run passes under both the interpreter and native, ASan clean, leak counter at 0. |
| M6 | Actors / OTP | Scheduler, actor fibers, reductions, Subject/Selector, receive with after, links, monitors, trap_exit, deep-copy send plus the Send check, actor.start, supervisor, timers. Crash and restart tests. |
| M7 | FFI + native deps | [native] manifest kinds, Resources with finalizers, the blocking pool, getrandom, an argon2 binding package. |
| M8 | HTML + net + HTTP | HTML literals plus rendering; reactor-backed TCP; HTTP/1.1 using picohttpparser over FFI (this also exercises FFI); Dict. |
| M9 | Tooling polish | The full v0 LSP feature set, the VS Code extension, louise test, louise fmt. |
| M10 | Demo + docs | examples/http_demo: supervisor → listener, session-store actor, handler actors → SSR pages, argon2 login, handlers for logging and DB mocks. Language reference and tutorial. |
Order to cut if scope must shrink:
- Formatter.
- Cargo native kind (C sources and pkg-config still cover argon2).
- Reuse analysis, then borrow inference (all-owned stays correct, just slower).
- Multi-thread scheduler (fall back to a single scheduler thread).
- Inlay hints.
Deferred to v1+:
- General
ctlin codegen, and multi-shot resumptions. - Work stealing.
- Client HTML target (wasm/JS).
- HKT, bigint, a package registry, monomorphization, explicit lifetimes and borrow annotations, and Rust bindgen-style generators.
5. Verification strategy
- Parser: insta CST snapshots; a deterministic mutation fuzz test asserting no panics and a lossless round-trip (CST text equals source). (M1: a stable-Rust test instead of cargo-fuzz, which needs nightly; it runs in CI on every push.)
- Type checker:
tests/ui/*.lsewith inline//~ ERRORand//~ TYPEexpectations (compiletest-style). - Codegen (differential): every
tests/run/*.lseruns in the reference interpreter and natively, and stdout must match.- Native runs use
-fsanitize=address,undefinedin CI. - The debug runtime asserts zero live objects at exit, the Perceus correctness oracle.
- Native runs use
- Runtime: Rust unit tests,
loomfor mailbox and scheduler concurrency, and stress tests (100k actors, crash and restart storms). - LSP: integration tests that drive the server over JSON-RPC (open, edit, hover, definition) on fixture projects.
- End to end:
louise build examples/http_demo && ./http_demo, then exercise login and pages withcurlwhile killing handler actors and checking that supervisors restart them.
6. Top risks
- Perceus combined with yield-unwinding correctness (leaks, double frees). Mitigations: the M0 C spike, the leak oracle, ASan, and the differential interpreter.
- Scope. v0 is a vertical slice spanning a compiler, a runtime and tooling. Each milestone must stay demoable, and the cut order above is the pressure valve.
- C toolchain variance.
musttailavailability and stack-switch asm differ per platform. v0 targets x86_64 and aarch64 Linux (plus macOS if cheap) and documents this. - Cost of an error-tolerant, incremental checker. It is mitigated by designing it in at M1/M2 rather than retrofitting.