# Louise v0 — Language & Compiler Plan > **v0 is done** (issue #13). What it deferred is planned in the [v1 roadmap](roadmap-v1.md). > **Revised 2026-10-09** by the project owner. Revision 1 of ADRs 0001–0004 changes these items: > - `Ref` is scoped to regions; > - `send` moves, shares or copies; > - `ctl` compiles 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 `@test` and an extended `@derive`. > > Where this plan and the ADRs differ, the ADRs win. > > Approved 2026-10-08. Decisions are detailed in [docs/adr/](adr/) and [runtime-abi.md](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, `@extern` FFI 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) ```louise 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 ("rendering " <> u.name)

{text u.name}

} pub fn main :: -> () / { 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 / -> a / { handle { action () } with { log msg -> io.println msg // `fn` op: resume is implicit } } ``` **Naming:** - Types are Uppercase (`Int`, `List`); 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 / `. If the row is omitted, the function is total (pure). - ⚠ `pub fn` requires a full signature, including the effect row. Local and private functions are inferred. - Panics are not tracked. A failed match, Int overflow or explicit `panic` unwinds 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 { fn show(x: a) -> String }`, `impl Show {..}`, `where Show`. - 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 `` 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::Error` silences follow-on errors, and inference continues per item. **Incremental model:** - ⚠ Decide before M2: per-item queries keyed by stable item IDs, behind a `Db` trait. - Start with simple per-file memoization and migrate to salsa if it becomes needed. - Required `pub` signatures 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](adr/0010-lexical-handlers.md), so there is no `mask`.) - ⚠ Generalize a `let` only 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* ctx` first: yielding flag, evidence vector, reduction counter, current actor. - Thread-locals are never used for this state. - ⚠ **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. 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. - ⚠ `drop` is 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 `!Send` hazards; 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 ``: `spawn`, `send`, `receive`, `self`, `link`, `monitor`, `exit`, `trap_exits`. - Tests use real actors as fakes, with virtual time; a handler of `` is possible but not a practical mock (ADR 0004, note of 2026-10-12). **Typed mailboxes:** - ⚠ `Subject` (pid + unique tag) and `Selector` for typed selective receive with `after` timeouts, as in Gleam OTP. - This lets `call` replies, monitor DOWN messages and timer ticks each have their own types. **Sending messages:** - `send` deep-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 `Bytes` and thread-safe Resources are *shared* with atomic RC instead of copied. **Send safety:** - ⚠ A static `Send` auto-trait is checked on `Subject` message 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.start` is a gen_server-like abstraction with typed `call` and `cast`. - `supervisor` provides 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 `blocking` runs 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` ADT, with `type Html = Element`. - Variants: element, text, fragment, raw. **Typing rules:** - ⚠ A child `{e}` must be `Element` or `List>`, unified with the parent's `msg`. - Text goes through an explicit `text(x)` call, using a `ToText` trait. - 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.render` escapes by default and writes to a rope/iolist (`Bytes` builder), never by repeated string concatenation. ### 3.7 FFI and native dependencies **Declaring externs:** ```louise @extern c "argon2id_hash_encoded" blocking fn argon2_hash :: pw: String salt: Bytes t: Int m: Int p: Int -> Result / ``` - Allowed types: - Int, Float, Bool. - String and Bytes, passed *borrowed* as ptr+len. - Owned returns built through `tl_bytes_alloc` / `tl_string_alloc`. - `Resource`, an opaque handle with a finalizer, marked `thread_safe` or not. - The effect row is mandatory and defaults to ``. - ⚠ `@extern` itself is built in **M5**, because std IO and strings call into `louise_rt`. **Native deps in `louise.toml` (M7):** ```toml [native.argon2] kind = "c" # c | static | pkg-config | cargo sources = ["vendor/argon2/src/*.c"] include = ["vendor/argon2/include"] ``` - `kind = "cargo"` builds a `staticlib` crate that exports `extern "C"` functions using the `louise-ffi` types. 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 fmt` formats from the CST; this is the last item in v0. - `louise test` runs `test fn`s from `std/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, `` 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:** 1. Formatter. 2. Cargo native kind (C sources and pkg-config still cover argon2). 3. Reuse analysis, then borrow inference (all-owned stays correct, just slower). 4. Multi-thread scheduler (fall back to a single scheduler thread). 5. Inlay hints. **Deferred to v1+:** - General `ctl` in 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/*.lse` with inline `//~ ERROR` and `//~ TYPE` expectations (compiletest-style). - **Codegen (differential):** every `tests/run/*.lse` runs in the reference interpreter *and* natively, and stdout must match. - Native runs use `-fsanitize=address,undefined` in CI. - The debug runtime asserts zero live objects at exit, the Perceus correctness oracle. - **Runtime:** Rust unit tests, `loom` for 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 with `curl` while killing handler actors and checking that supervisors restart them. ## 6. Top risks 1. **Perceus combined with yield-unwinding correctness** (leaks, double frees). Mitigations: the M0 C spike, the leak oracle, ASan, and the differential interpreter. 2. **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. 3. **C toolchain variance.** `musttail` availability and stack-switch asm differ per platform. v0 targets x86_64 and aarch64 Linux (plus macOS if cheap) and documents this. 4. **Cost of an error-tolerant, incremental checker.** It is mitigated by designing it in at M1/M2 rather than retrofitting.