# 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. `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](../adr/0036-clock-and-random-effects.md)). The filesystem/network decisions and migration are in [ADR 0084](../adr/0084-capability-roots.md), 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 `` | 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: ```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`, `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 / `, 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 `net` governs operations that need ambient resolver/opening authority: | Operation | Row | Why | |---|---|---| | `net.resolve host` | `` | Consults the host resolver (native DNS on the I/O pool) | | `net.listen host port`, `net.connect host port` | `` | Resolves once, then retries opening each address in order | | `net.listen_at address port`, `net.connect_to address port` | `` | Deliberately exposed address-level operations behind those wrappers | | `http.listen`, `tls.dial` | `` (plus TLS dial's ``) | Opens a new listener/connection | | `net.accept`, `port`, `peer`, `read`, `write`, `close`, `close_listener` | `` | Uses an already-handed listener/socket Resource | | `std/io.Stream` TCP/TLS `read`/`write`/`close` | `` | Uses the stream object; no trait-wide net requirement | | `http.serve*` on an existing listener | `` (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 | `` | 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 `` 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 ``. 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: ```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/network-opening `/ ` facade and no automatic `@deprecated` diagnostics. For sockets, move only opening authority: `net.resolve`, `net.listen`/`connect`, `http.listen` and `tls.dial` change to `` (TLS dial retains `` too). Keep `` 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: - `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 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.