
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
Capabilities and effect roots
Louise uses ordinary typed effects both to describe what a function may do and, for selected standard effects, to locate its implementation. With std/file.fs, for example, a function that reads a file advertises / <fs> and can run against either the runtime's real filesystem root or a lexical fake. No public capability value is added to the call: file.read path remains file.read path.
The model extends the existing clock, random and proc design (ADR 0036). The filesystem decision and migration are in ADR 0084.
What a function may touch
| Definition | What its operations mean |
|---|---|
std/process.proc | Starting and coordinating actors, subjects, links and timers |
std/time.clock | Wall and scheduler clocks |
std/random.random | System random bytes; the rest of std/random is built on them |
std/file.fs | Whole-file byte reads/writes, existence, size and directory listing |
These are effects with operations, so their hidden evidence instances distinguish one lexical handler from another. The compiler identifies the built-in effects by definition, not by the spelling fs or clock of an unrelated user effect. The op-less io effect is not an instance of this root table.
A minimal real-root entry can be annotated as follows:
import std/file.{type fs}
import std/io
pub fn main :: -> () / <io, fs>
{
io.println (show (file.read "message.txt"))
}
read is the UTF-8 wrapper over fs.read_bytes; write similarly wraps write_bytes. The complete public byte-level operations are read_bytes, write_bytes, exists, size and list_dir, all under fs. Native real-root operations use the I/O blocking pool while their actor is parked.
Where real roots come from
The runtime provides real proc, clock, random and fs handlers around main and each test. Entry parameters remain unit-only; the evidence is implicit in lowering. Lowering records the root kinds in the entry's own row order.
Every ordinary local actor receives the same four root kinds, derived from std/process.spawn's body row. This is deliberately uniform and global to the program today: it is not a per-actor least-authority policy. A program that does not reach std/process does not acquire an invented process/file dependency just to populate unused actor roots.
An outer entry or orchestration function need not declare fs merely because it creates a callback whose row includes fs. Creating or scheduling that callback is not an outer file operation. The callback still advertises fs and receives its real root through the HTTP/process actor contract; the outer main/web entry keeps only the operations it performs itself.
A lexical fake
Install a normal handle around the action whose fs should be replaced. Its action has a type of the form fn() -> a / <fs | e>, so unrelated effects in e propagate unchanged. Import the five operation names when writing the clauses:
import std/bytes
import std/file.{type fs, read_bytes, write_bytes, exists, size, list_dir}
fn with_fake :: action: fn() -> a / <fs | e> -> a / <e>
{
handle { action () }
with
{ read_bytes _ -> Ok(bytes.from_string "not from disk")
, write_bytes _ _ -> Ok(())
, exists _ -> True
, size _ -> Ok(13)
, list_dir _ -> Ok(["fake.txt"])
}
}
A useful stateful fake can place a Dict<String, Bytes> in a region-owned Ref, as examples/http_demo/test/app_test.lse does. The handler owns that state only for its lexical extent; the real root never holds a process-global fake slot. The demo's fixture explicitly limits file count, path bytes and content bytes so a broken test cannot request an unbounded in-memory filesystem. Seed paths declare their parent directories; later writes require an implicit current/root directory or a represented non-empty parent, and neither fake nor real writes create directories.
The whole demo's authentication path requires native Argon2 through C; there is deliberately no interpreter emulation. For an isolated both-backend proof, fake_files_cover_operations_and_static_routes_without_leaking_writes combines all five fake operations and a static fake-request transcript without seed hashing, RNG, C calls or environment reads. The real on-disk/native request remains a separate control.
Fake handlers do not follow process.spawn, spawn_link or spawn_monitor. The children receive the runtime roots, not the parent's fake, and the usual Send rules still apply to the closure's actual captures. Install another lexical handler inside the child if that is what a test intends.
For the interpreter's test cache, real path reads and exists/metadata/listing calls record the path as an input; a real write is unrepeatable. A lexical fake records neither host paths nor a real write. Its source participates in ordinary module hashes, so changing the fake invalidates its cached result normally.
Opening authority versus an object already opened
A root operation can represent authority to open or locate a new external object, as file operations name paths. Once a library returns a resource, that resource can instead be the object capability for its own later operations: possession of the handle controls what its methods mean. The distinction matters particularly for sockets and listeners, whose streaming traits must not acquire an unrelated global requirement merely to use a handle already handed to a function. D1 does not implement the network decision; it belongs to the separate network migration review.
Remote entries are denied fs by default
A @remote function cannot declare std/file.fs. Compilation reports E0707 before distribution can dispatch it. A user-written effect named fs has no special status.
There is also a runtime provenance check, because proc must remain available and a remote entry could otherwise spawn a child with the full actor row. Every generated remote thunk marks its actor before calling user code. spawn, spawn_link and spawn_monitor, including nested descendants, inherit permanent fs denial. The real root then returns Error("fs: access denied to a remote actor") for reads, writes, size and listing, while exists returns False, without touching the path or blocking pool. This applies equally to in-process wire.dispatch tests and actual distribution. Ordinary local actors and their children retain real fs roots.
This is a conservative default until distribution has a reviewed host-authorization policy. It is not a general containment boundary around arbitrary native code or ffi.
Migration from ambient file I/O
This is an intentional breaking effect-row migration, not a hidden compatibility mode:
before: load : String -> Result<String, String> / <io>
after: load : String -> Result<String, String> / <fs>
Keep function names, argument lists and Result shapes. Update typed aliases, actor callbacks, HTTP/SSE/stream writer rows and any named functions passed to their expanded contracts. An inferred signature may need no text edit, but a full public signature must be explicit. There is no legacy real-filesystem / <io> facade and no automatic @deprecated diagnostics.
What this is not
Effect roots and fakes are dependency injection, not a security sandbox:
ffistill permits arbitrary native calls, including direct rebinding of retained runtime symbols;- op-less
iobehavior is unchanged; os.env, arguments, exit and signals are separate ambient powers;- TLS configuration and certificate/key/CA secret-file reads are separate from this fs fake;
- distribution transport and authorization are separate;
- a filesystem root can touch any path the host permits. Keep application-level path containment separately (the HTTP demo rejects traversal).
The current D1 scope delivers std/file.fs; it does not claim the later network/TLS migration, transparent TLS fakes, full in-memory socket transport, per-actor grants or distribution authorization.