# 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 `/ ` 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](../adr/0036-clock-and-random-effects.md)). The filesystem decision and migration are in [ADR 0084](../adr/0084-capability-roots.md). ## 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: ```louise import std/file.{type fs} import std/io pub fn main :: -> () / { 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 / `, so unrelated effects in `e` propagate unchanged. Import the five operation names when writing the clauses: ```louise import std/bytes import std/file.{type fs, read_bytes, write_bytes, exists, size, list_dir} fn with_fake :: action: fn() -> a / -> a / { 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` 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: ```text before: load : String -> Result / after: load : String -> Result / ``` 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 `/ ` facade and no automatic `@deprecated` diagnostics. ## What this is not Effect roots and fakes are dependency injection, not a security sandbox: - `ffi` still permits arbitrary native calls, including direct rebinding of retained runtime symbols; - op-less `io` behavior 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.