
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. std/net.net likewise marks name resolution and socket opening. No public capability argument is added: file.read path and net.connect host port keep those call shapes.
The model extends the existing clock, random and proc design (ADR 0036). The filesystem/network decisions and migration are in ADR 0084, which remains Proposed pending #44 engineering review.
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 |
std/net.net | Host resolution and listener/connection opening; later use of a returned socket is handle-mediated <io> |
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, net 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, fs and net 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 five root kinds, derived from std/process.spawn's body row in stable RootCap discriminant order (proc, clock, random, fs, net), never module/DefId order. The actor body's hidden capability parameters use this exact layout. 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/network dependency just to populate unused actor roots.
An outer entry or orchestration function need not declare fs/net merely because it creates a callback whose row includes those roots. 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
net governs operations that need ambient resolver/opening authority:
| Operation | Row | Why |
|---|---|---|
net.resolve host | <net> | Consults the host resolver (native DNS on the I/O pool) |
net.listen host port, net.connect host port | <net> | Resolves once, then retries opening each address in order |
net.listen_at address port, net.connect_to address port | <net> | Deliberately exposed address-level operations behind those wrappers |
http.listen, tls.dial | <net> (plus TLS dial's <io>) | Opens a new listener/connection |
net.accept, port, peer, read, write, close, close_listener | <io> | Uses an already-handed listener/socket Resource |
std/io.Stream TCP/TLS read/write/close | <io> | Uses the stream object; no trait-wide net requirement |
http.serve* on an existing listener | <io, proc> (plus its existing real rows) | Accepts through that listener object; does not resolve or listen again |
tls.connect on TCP / tls.accept on accepted TCP | <io> | Uses the supplied connection object and TLS configuration |
A returned listener or socket is therefore its object capability. Accepting creates another socket value, which is itself the authority for reads/writes/close. TLS takes over the TCP handle during upgrade. Existing nonblocking readiness retry/wakeups, kill/unwind and close-from-another-actor behavior belongs to these handle operations and is unchanged by the opening root.
A scoped net fake may resolve to a short fixed address list or force resolver/opening errors. The both-backend tests/run/net_fake.lse uses deterministic TEST-NET sentinels, including distinct errors on two addresses to prove retry order. Socket-producing fake paths return errors: no successful native Resource is forged. Real loopback tests remain the positive control. The interpreter's real net root still reports the established native-backend diagnostic rather than pretending to provide sockets.
Authority that remains separate
TLS configuration still really reads its CA/certificate/key paths through the existing native TLS implementation and <io> authority. Fake fs/net handlers do not intercept those secret-file reads, and the migration does not claim a TLS-secret root. Distribution's transport, listener, node identity and mTLS credentials likewise remain distribution authority; only the std helper's actual net.resolve calls acquire <net>. Neither statement is a process sandbox.
Remote entries are denied fs and net by default
A @remote function cannot declare std/file.fs or std/net.net. Compilation reports E0707 before distribution can dispatch it. User-written effects with those names have no special status.
There is also runtime provenance enforcement, 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 denial on both backends.
The fs root returns Error("fs: access denied to a remote actor") for reads, writes, size and listing, while exists returns False, without touching a path. Resolver, address-level listen and address-level connect all return Error("net: access denied to a remote actor") before inspecting a name, entering the resolver pool or touching a socket. For an in-range port, high-level listen/connect begin with that denied resolver too; an invalid port retains its earlier pure range error without invoking any root. Ordinary local actors and their children keep real roots, with the native fixture's loopback control proving the positive path. This applies equally to in-process wire.dispatch tests and actual distribution, including the two-process remote_network_descendants_are_denied_across_nodes regression.
This is a conservative default until distribution has a reviewed host-authorization policy. It is not a general containment boundary around arbitrary native code, distribution transport, an already-provided handle or ffi.
Migration from ambient file/network 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/network-opening / <io> facade and no automatic @deprecated diagnostics.
For sockets, move only opening authority: net.resolve, net.listen/connect, http.listen and tls.dial change to <net> (TLS dial retains <io> too). Keep <io> on existing-socket Stream methods, accept/read/write/peer/close, listener serving and TLS over an already-supplied connection. http.serve therefore does not demand resolver authority. Update std/dist resolution/startup, fetch worker internals and PostgreSQL opening/pool/cancel paths without marking pure formatters or existing-handle query operations as net. All actor callback duplicates move to the common five-root row together; that uniform provisioning is not a claim that a given callback opened a socket.
ABI 12 is retained: TL_ROOT_NET = 4 is appended after fs, existing discriminants and raw tl_net_* signatures do not move, and actor capacity becomes five with old-runtime kind/count failure checks. No source-visible parameter is inserted into old C calls.
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 fs/net fakes;
- 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 D1+D2 scope delivers std/file.fs and opening-root std/net.net; it does not claim transparent TLS fakes, full in-memory socket transport, OS/FFI containment, per-actor grants or distribution authorization.