tobogganSe connecter

louise

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

345 lignes · 18747 octetsBrut · Historique

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:

  • 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/ 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, @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)

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 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<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::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, 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 kindv0 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 <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) 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<msg> ADT, with type Html = Element<Never>.
  • Variants: element, text, fragment, raw.

Typing rules:

  • ⚠ A child {e} must be Element<msg> or List<Element<msg>>, 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:

@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, marked thread_safe or not.
  • The effect row is mandatory and defaults to <ffi>.
  • ⚠ @extern itself is built in M5, because std IO and strings call into louise_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 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 fns from std/test.

4. Milestones (each ends with something runnable)

#MilestoneExit criteria
M0FoundationsWorkspace, 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.
M1SyntaxLexer with HTML mode, error-tolerant parser, rowan CST, insta snapshots, a fuzz test with no panics, louise check reporting parse errors.
M2Names + core typesResolution, 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.
M3Effects in typeseffect declarations, row inference, handle/with, mask, total-only generalization, <st> refs. LSP hover shows effects.
M4Core + interpreterLowering to typed ANF Core; the reference interpreter runs everything, including general ctl. louise run --interp gives the first programs running.
M5Native backendEffect 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.
M6Actors / OTPScheduler, 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.
M7FFI + native deps[native] manifest kinds, Resources with finalizers, the blocking pool, getrandom, an argon2 binding package.
M8HTML + net + HTTPHTML literals plus rendering; reactor-backed TCP; HTTP/1.1 using picohttpparser over FFI (this also exercises FFI); Dict.
M9Tooling polishThe full v0 LSP feature set, the VS Code extension, louise test, louise fmt.
M10Demo + docsexamples/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.