kobako 0.28.0 → 0.29.0

data/README.md

@@ -45,7 +45,7 @@ gem install kobako
 
 ## Quick Start
 
-The same untrusted script runs identically from either host frontend. It executes inside the Wasm guest and cannot read your filesystem, open sockets, or touch your environment.
+The same untrusted script runs identically from either host frontend. It executes inside the Wasm guest and reaches no file you have not mounted for it, no socket, and none of your environment.
 
 ```ruby
 require "kobako"
@@ -129,12 +129,13 @@ These terms name the concepts the rest of this README builds on.
 | Invocation | — | One run of guest code, by `#eval` or `#run`. |
 | Execution | `Kobako::Execution` | The frozen record an Invocation leaves. |
 | Service | — | A host object the guest reaches by name, such as `MyService::KV`. |
+| Mount | — | A `Kobako::Filesystem` placed at a guest path by `Sandbox#mount`, for the guest's `File`. |
 | Context | `Kobako::Context` | The per-Invocation object the optional block receives. |
 | Snippet | — | Guest source or bytecode replayed at the start of every Invocation. |
 | Handle | `Kobako::Handle` | An opaque reference to a host object the wire cannot carry by value. |
 | Block | — | Guest code passed alongside a Service call. |
 
-A Sandbox keeps nothing from one Invocation to the next. An Execution holds what the run produced, wrote, and consumed: `#value`, output captures, and `#usage`. A failed run raises, carrying its Execution on the error's `#execution`. A Service is the guest's only route to a host resource. A Context's `ctx.bind` supplies a Service object for that one run. A Handle names its object only within the Invocation that issued it. A Block stays in the guest; each `yield` to it is a synchronous round-trip.
+A Sandbox keeps nothing from one Invocation to the next. An Execution holds what the run produced, wrote, and consumed: `#value`, output captures, and `#usage`. A failed run raises, carrying its Execution on the error's `#execution`. A Service or a Mount is the guest's only route to a host resource. A Context's `ctx.bind` supplies a Service object for that one run. A Handle names its object only within the Invocation that issued it. A Block stays in the guest; each `yield` to it is a synchronous round-trip.
 
 ## Usage
 
@@ -143,6 +144,7 @@ Each section below stands on its own; this is the order they build in.
 | If you want to | Read |
 |---|---|
 | let guest code call into your host | [Services](#services), [Per-Invocation Bindings](#per-invocation-bindings), [Service Blocks](#service-blocks) |
+| let guest code read and write files | [Mounts](#mounts) |
 | see what a run produced or why it failed | [Output Capture](#output-capture), [Error Handling](#error-handling), [Invocation Lifecycle](#invocation-lifecycle) |
 | bound what a run may consume | [Resource Limits](#resource-limits), [Concurrency](#concurrency), [Pooling](#pooling) |
 | hand host objects across the boundary | [Handle Management](#handle-management) |
@@ -150,7 +152,7 @@ Each section below stands on its own; this is the order they build in.
 
 ### Services
 
-`bind` any Ruby object as a Service at a constant-path name. The guest reaches it as a `MyService::KV` (or top-level `File`) proxy. Through the Transport wire, the guest invokes the public methods the object's own class defines.
+`bind` any Ruby object as a Service at a constant-path name. The guest reaches it as a `MyService::KV` (or top-level `Clock`) proxy. Through the Transport wire, the guest invokes the public methods the object's own class defines.
 
 ```ruby
 class User
@@ -170,7 +172,7 @@ sandbox.eval(<<~RUBY)
 RUBY
 ```
 
-Each `::`-separated path segment must match `/\A[A-Z]\w{0,65533}\z/`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation (see [Invocation Lifecycle](#invocation-lifecycle)); later `#bind` raises `ArgumentError`.
+Each `::`-separated path segment must match `/\A[A-Z]\w{0,65533}\z/`. A path under `Kobako`, which the Guest Binary keeps for itself, raises `ArgumentError`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation (see [Invocation Lifecycle](#invocation-lifecycle)); later `#bind` raises `ArgumentError`.
 
 ### Per-Invocation Bindings
 
@@ -184,6 +186,84 @@ sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
 
 `ctx.bind` also shadows an already-bound path for that one run. The Context is spent once the block returns, so a `ctx` captured out of it raises `ArgumentError`. Choosing the object per invocation lets concurrent Threads invoke a single Sandbox and still keep their identities apart. The [multi-tenant example](examples/multi-tenant/) runs that shape end to end.
 
+### Mounts
+
+`mount` places a `Kobako::Filesystem` at an absolute guest path, where the guest's `File` reads it. The default access is `:read`, so a write beneath it raises `Errno::EROFS` in the guest.
+
+```ruby
+sandbox.mount("/config", Kobako::Filesystem::Memory.new("app.yml" => yaml))
+sandbox.mount("/tmp", Kobako::Filesystem::Temporary.new, access: :read_write)
+sandbox.mount("/data", Kobako::Filesystem::Directory.new("var/data")) { |path, _access| path.end_with?(".csv") }
+
+sandbox.eval('File.read("/config/app.yml")')
+```
+
+| Kind | Holds |
+|---|---|
+| `Memory.new(files = {}, limit:, inodes:)` | files in memory, shared by every invocation |
+| `Temporary.new(limit:, inodes:)` | files in memory, empty at every invocation |
+| `Directory.new(path)` | a host directory; nothing outside it is reachable |
+| `Overlay.new.layer(fs, access:)` | Layers stacked into one view, the first added on top |
+
+A Memory or Temporary is bounded as a tmpfs mount is. Its files hold 64 MiB unless `limit:` gives another size in bytes. It holds one file or directory for each 4 KiB of that limit, and its root, unless `inodes:` gives another count. `nil` lifts either bound, and the guest raises `Errno::ENOSPC` past one.
+
+A block decides each open and each change that reaches the Mount in the access's place, asked at most once for each. A falsy answer or a `StandardError` fails that call as `Errno::EACCES`. Mounts seal with the Sandbox like a `bind`, and `ctx.mount` replaces one for a single run.
+
+#### Guest File
+
+The guest's `File.open` takes a mode String such as `"r"`, `"w+"`, or `"wx"`, or an Integer of `File::Constants` flags, valued as CRuby's on Linux. An exclusive create lets Sandboxes sharing a directory agree on a lock file. The critical flag `disable_file` removes `File` from the guest altogether.
+
+Beneath a mount, `File.open` and `IO.new` answer as CRuby does over a Linux directory. Where they differ, they only refuse more:
+
+| When | The guest sees |
+|---|---|
+| nothing is mounted | `NotImplementedError` |
+| a block refuses a change | `Errno::EACCES` where a read-only mount says `Errno::EROFS` |
+| a Ruby Filesystem's file without `append` is asked to append | `Errno::ENOTSUP` on the write |
+| an Integer mode holds a flag kobako does not honor, or `WRONLY` beside `RDWR` | `Errno::EINVAL` |
+| a mode names an encoding, such as `"r:utf-8"` | `ArgumentError` |
+| `IO.new` wraps stdout or stderr in a mode other than `"w"` | `ArgumentError` |
+| `disable_file` is set | no `File` constant |
+
+#### Overlays
+
+`layer` adds a Filesystem beneath the Layers already there and answers a new Overlay. Each Layer is `:read`, the default, or `:read_write` on its own.
+
+```ruby
+overlay = Kobako::Filesystem::Overlay.new
+  .layer(Kobako::Filesystem::Temporary.new, access: :read_write) # empty every run
+  .layer(Kobako::Filesystem::Directory.new("app"))                # never written
+sandbox.mount("/app", overlay, access: :read_write)
+```
+
+A change to a file in a writable Layer stays there. A read-only Layer's file is first copied up to the nearest writable Layer above it, and a new or renamed file lands in the topmost one. A lower writable Layer's file does not move, raising `Errno::EXDEV`, as across devices. A removal hides what a lower Layer keeps with an [OCI whiteout](https://github.com/opencontainers/image-spec/blob/main/layer.md#whiteouts), `.wh.<name>`, kept in the topmost writable Layer. Names starting with `.wh.`, in any case, are therefore reserved.
+
+#### Filesystems in Ruby
+
+Any object answering `open` and `stat` mounts as a Filesystem, directly or as a Layer. Its methods follow Ruby's `File`, `Dir`, and `IO`, so a real `::File` can answer as an open file.
+
+| Method | Answers |
+|---|---|
+| `open(path, flags)` | an open file, below |
+| `stat(path)` | an object answering `directory?`, `size`, and `ino`, as `File::Stat` does |
+| `children(path)` | entry names, as `Dir.children` gives them |
+| `mkdir` · `rmdir` · `unlink` · `rename(from, to, directory:)` | optional; without one, that change raises `Errno::EROFS` |
+
+A `stat` may also answer `dev`; without one, the Filesystem stands for a single device. An `ino` names one directory while the guest holds it open, and names match exactly, as a block judges them. A path is relative to the mount, the empty path being its root, and `flags` are `File::Constants`. A `rename` told `directory: false` moves only a file and `true` only a directory; `nil` moves either. An `Errno` the guest has a class for reaches the script as itself, and any other `StandardError` as `Errno::EIO`. Every call re-enters Ruby, and its time counts toward `timeout:` without being interrupted.
+
+##### Open Files
+
+The file `open` answers takes the guest's reads and writes, each method named as `IO` names it.
+
+| Method | Answers | Without it |
+|---|---|---|
+| `pread(length, offset)` · `size` | bytes, `nil` or `EOFError` at the end; the length | required |
+| `pwrite(data, offset)` · `truncate(length)` | bytes written; nothing | that change raises `Errno::EROFS` |
+| `append(data)` | where the file then ends, as `IO#pos` does | an append raises `Errno::ENOTSUP` |
+| `fsync` · `close` | nothing | nothing to flush or release |
+
+An `append` writes all of `data` at the end in one step, so another writer's append never lands over it.
+
 ### Output Capture
 
 Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and read off the run's Execution, independently of its `#value`. Each invocation captures its own; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
@@ -225,7 +305,7 @@ Each of these carries the failed run's Execution on `#execution`. A rescue reads
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
 | `Kobako::NoServiceError`        | `ServiceError` | Nothing bound there, a dead Handle, or a method the guest may not call |
-| `Kobako::ServiceArgumentError`  | `ServiceError` | The arguments did not fit the Service method         |
+| `Kobako::ServiceArgumentError`  | `ServiceError` | The call would not bind, or the Service raised `ArgumentError` |
 | `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
 | `Kobako::UnsupportedFlagError`  | `SandboxError` | The Guest Binary does not recognise a critical `#flag`; no script ran |
@@ -233,6 +313,15 @@ Each of these carries the failed run's Execution on `#execution`. A rescue reads
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` fields when the guest produced a panic envelope.
 
+#### Host Exceptions
+
+A Service, a mount's block, or a Filesystem written in Ruby is your code running inside the run. What it raises splits by class.
+
+| Raised by your code                     | Result                                        |
+|-----------------------------------------|-----------------------------------------------|
+| a `StandardError`                       | the guest sees a failure it may rescue        |
+| `Interrupt`, `exit`, `throw`, `Timeout` | the run ends; the invocation raises it as is  |
+
 ### Resource Limits
 
 Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Execution#usage`](lib/kobako/execution.rb) for actual consumption — populated on every outcome, so a rescued trap reports it just as a completed run does.
@@ -240,22 +329,36 @@ Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memo
 ```ruby
 sandbox = Kobako::Sandbox.new(
   timeout:      5.0,              # seconds, default 60.0
-  memory_limit: 10 * 1024 * 1024, # bytes,   default 1 MiB
+  setup_timeout: 2.0,             # seconds, default 10.0
+  memory_limit: 10 * 1024 * 1024, # bytes,   default 4 MiB
   stdout_limit: 64 * 1024,        # bytes,   default 1 MiB
-  stderr_limit: 64 * 1024
+  stderr_limit: 64 * 1024,
+  open_file_limit: 16             # descriptors, default 1024
 )
 ```
 
-| Cap            | Raises                     | Default |
-|----------------|----------------------------|---------|
-| `timeout`      | `Kobako::TimeoutError`     | 60.0 s  |
-| `memory_limit` | `Kobako::MemoryLimitError` | 1 MiB   |
-| `stdout_limit` | output clipped (no raise)  | 1 MiB   |
-| `stderr_limit` | output clipped (no raise)  | 1 MiB   |
+| Cap               | Raises                         | Default |
+|-------------------|--------------------------------|---------|
+| `timeout`         | `Kobako::TimeoutError`         | 60.0 s  |
+| `setup_timeout`   | `Kobako::SetupError` at `new`  | 10.0 s  |
+| `memory_limit`    | `Kobako::MemoryLimitError`     | 4 MiB   |
+| `stdout_limit`    | output clipped (no raise)      | 1 MiB   |
+| `stderr_limit`    | output clipped (no raise)      | 1 MiB   |
+| `open_file_limit` | `Errno::EMFILE` in the guest   | 1024    |
 
-`memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
+`setup_timeout` bounds instantiating a Guest Binary and reading its ABI version, not compiling it. It applies the first time a path is loaded; later Sandboxes on that path skip the check. A Pool builds each Sandbox at its first checkout, so its `SetupError` raises from `with`. `memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget. `open_file_limit` counts every descriptor one invocation holds, the three standard ones and each Mount's included, so a guest cannot exhaust the host process's own.
 
-Beyond the four caps, `profile:` requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources, an explicit trade of reproducibility. Filesystem, environment, and network stay unreachable under either. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/guides/security.md`](docs/guides/security.md) § Isolation Profiles.
+#### Isolation Profile
+
+Beyond the caps, `profile:` requests the Sandbox's isolation posture on a two-rung ladder.
+
+```
+:permissive  <  :hermetic (default)
+live clock      frozen clock
+live entropy    constant entropy
+```
+
+`:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources, an explicit trade of reproducibility. The guest reaches no ambient filesystem, environment, or network under either. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/guides/security.md`](docs/guides/security.md) § Isolation Profiles.
 
 ### Concurrency
 
@@ -358,7 +461,7 @@ A Sandbox holds no state from any run, so Threads sharing one are equally safe.
 
 ### Service Blocks
 
-A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch.
+A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest. Its `break` / `next` / `return` / exceptions follow normal Ruby semantics: an exit lands where it would through a plain method.
 
 ```ruby
 sandbox.bind("Seq::Map", ->(items, &blk) { items.map(&blk) })
@@ -367,13 +470,28 @@ sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }').value
 # => [2, 4, 6]
 ```
 
-A `yield` that cannot complete raises at the Service's call site, so the Service may rescue it. Left unrescued, a `BlockError` hands the guest its own exception back; the other two fail the Service call.
+A `yield` that cannot complete raises at the Service's call site, so the Service may rescue it. Left unrescued, a `BlockError` hands the guest its own exception back; the others fail the Service call.
 
 | Class                      | Trigger at `yield`                    |
 |----------------------------|---------------------------------------|
 | `Kobako::BlockError`       | The guest block raised                |
 | `Kobako::YieldValueError`  | An argument cannot cross to the guest |
 | `Kobako::UnsupportedError` | The Guest Binary serves no block      |
+| `ThreadError`              | The block runs off the calling Fiber  |
+
+#### Block Fiber
+
+A block runs only on the Fiber that called the Service. The guest's Wasm stack lives on that Fiber's native stack, so entering it from another raises `ThreadError` before the block runs. CRuby itself lets a block run anywhere; kobako narrows that to keep the guest's stack checks sound.
+
+```
+Service on the calling Fiber
+  ├─ blk.call / yield                     ─> runs in the guest
+  ├─ Thread.new { blk.call }              ─> ThreadError
+  └─ Enumerator.new { |y| y << blk.call }
+       .next   (runs its body on a Fiber) ─> ThreadError
+```
+
+`Enumerator#next` counts as another Fiber, because it runs the enumerator's body on one. Internal iteration such as `each` or `map` stays on the calling Fiber and runs the block normally.
 
 ### Handle Management
 
@@ -391,7 +509,7 @@ sandbox.eval('Factory::Make.call("Bob").greet').value  # => "hi, Bob"  (Handle r
 sandbox.eval('Factory::Make.call("Bob")').value        # => #<Greeter @name="Bob">  (Handle restoration)
 ```
 
-A `break` value from a guest block is the one exception. It unwinds back to the guest Service call rather than to host code, so a Handle in it stays a Handle. Restoring would just re-wrap the same object into a new id on the return trip.
+A `break` value from a guest block never reaches host code. It stays in the guest while the Service unwinds, so a Handle in it stays a Handle.
 
 #### Per-dispatch Handles
 
@@ -461,8 +579,8 @@ Use the source form for snippets authored in your repo; use the bytecode form wh
 An Extension teaches the guest a native-style constant by pairing a guest idiom (`source`) with an optional host `backend`. `Sandbox#install` composes the two through the existing `#preload` and `#bind` verbs, adding no wire or Guest Binary surface. Pure operations run in-guest with no round-trip. The rest dispatch to the backend under the same isolation and reflection guarantees as any bound Service ([`docs/guides/extensions.md`](docs/guides/extensions.md)).
 
 ```ruby
-FILE = <<~'MRUBY'
-  class File
+VFS = <<~'MRUBY'
+  class Vfs
     extend Kobako::Proxy
     def self.basename(path) = path.split("/").last || ""  # pure: runs in-guest
     # read / write are undefined here, so they dispatch to the backend
@@ -471,16 +589,16 @@ MRUBY
 
 sandbox.install(
   Kobako::Extension.new(
-    name: :File,
-    source: FILE,
+    name: :Vfs,
+    source: VFS,
     backend: Kobako::Extension::Backend.new(
-      path: "File",
-      provider: -> { OverlayFileSystem.new(root) }  # invoked once per invocation
+      path: "Vfs",
+      provider: -> { CopyOnWriteFiles.new(root) }  # invoked once per invocation
     )
   )
 )
 
-sandbox.eval('File.read("sample.txt")')  # dispatches to the backend's #read
+sandbox.eval('Vfs.read("sample.txt")')  # dispatches to the backend's #read
 ```
 
 A backend declares the bound object's lifetime by keyword, never by inference — so a static object that happens to be callable stays unambiguous.
@@ -491,12 +609,12 @@ A backend declares the bound object's lifetime by keyword, never by inference
 | `provider:` | A no-argument callable invoked per invocation                               |
 | neither     | A fillable, standing for `Kobako::Unresolved` until `ctx.bind` supplies the run's object |
 
-A writable backend takes `provider:`, so its state cannot leak across runs. kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked `File` that reads through to disk while protecting it from guest writes.
+A writable backend takes `provider:`, so its state cannot leak across runs. kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked virtual file that reads through to disk while protecting it from guest writes.
 
 ## Security
 
-kobako isolates the guest, but **what it may reach is whatever you `bind`** — and `bind`
-exposes every public method the object's own class defines. Inherited, mixed-in, and built-in
+kobako isolates the guest, but **what it may reach is whatever you `bind` or `mount`**.
+`bind` exposes every public method the object's own class defines. Inherited, mixed-in, and built-in
 methods stay out of reach, but the class's own surface does not. Bind a purpose-built object
 scoped to the task, not a capable one whose other methods leak more than you intend.
 
@@ -524,23 +642,23 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
 | First `Sandbox.new` ever for a Guest Binary (Module JIT, then disk-cached) | ~500 ms once per machine |
-| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~3 ms one-time        |
+| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~1.4 ms one-time      |
 | Subsequent `Sandbox.new` (caches warm)                       | ~3 µs                 |
-| Warm `#eval` with one Service call on a reused Sandbox       | ~70 µs                |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~79 µs                |
-| Service call amortized inside one invocation                 | ~5.8 µs               |
-| Snippet replay per invocation                                | ~7.0 µs each          |
+| Warm `#eval` with one Service call on a reused Sandbox       | ~62 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~57 µs                |
+| Service call amortized inside one invocation                 | ~4.9 µs               |
+| Snippet replay per invocation                                | ~2.7 µs each          |
 | Per additional idle Sandbox (RSS)                            | < 1 KB                |
 
-The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance, which is why a thousand idle tenants cost ~34 MB total. The canonical boot state is baked into the artifact and instantiated per invocation. A +10% regression on any gated benchmark blocks release.
+The Cranelift JIT runs once per machine and wasmtime release — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance, which is why a thousand idle tenants cost ~37 MB total. The canonical boot state is baked into the artifact and instantiated per invocation. A +10% regression on any gated benchmark blocks release.
 
 #### Throughput Levers
 
 | Choice | What it changes |
 |---|---|
-| `gvl: :hold` (default) | ~16k `#eval`/s in aggregate, at any Thread count |
+| `gvl: :hold` (default) | ~15–20k `#eval`/s in aggregate, at any Thread count |
 | `gvl: :release` | lifts that ceiling for compute-bound scripts (see [Concurrency](#concurrency)) |
-| `match?` over `=~` | `=~` (~5 µs/match) costs about 5× `match?` (~1.0 µs) |
+| `match?` over `=~` | `=~` (~5.6 µs/match) costs about 6× `match?` (~0.9 µs) |
 
 Under `:hold` the GVL serializes wasm work, though Ruby-side `#eval` setup still overlaps. `=~` eagerly builds the `MatchData` and match globals, so prefer `match?` for boolean tests. Regexp is an opt-in capability gem, excluded from the default binary and the gated set. Its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)).
 

data/ROADMAP.md

@@ -24,3 +24,8 @@ row below links a feature to its scenarios and to where its code starts.
 | ✅ [Regexp](docs/spec/behavior/regexp.md) | [wasm/kobako-regexp/src/regexp.rs](wasm/kobako-regexp/src/regexp.rs) |
 | ✅ [Regexp over String](docs/spec/behavior/regexp-string.md) | [wasm/kobako-regexp/src/string_ext.rs](wasm/kobako-regexp/src/string_ext.rs) |
 | ✅ [MatchData](docs/spec/behavior/regexp-matchdata.md) | [wasm/kobako-regexp/src/matchdata.rs](wasm/kobako-regexp/src/matchdata.rs) |
+| ✅ [Guest File](docs/spec/behavior/file.md) | [wasm/kobako-io/src/file.rs](wasm/kobako-io/src/file.rs) |
+| ✅ [Filesystem](docs/spec/behavior/filesystem.md) | [crates/kobako-runtime/src/filesystem.rs](crates/kobako-runtime/src/filesystem.rs) |
+| ✅ [Mount](docs/spec/behavior/mount.md) | [lib/kobako/catalog/mount.rb](lib/kobako/catalog/mount.rb) |
+| ✅ [Ruby Filesystem](docs/spec/behavior/ruby-filesystem.md) | [ext/kobako/src/runtime/filesystem/ruby.rs](ext/kobako/src/runtime/filesystem/ruby.rs) |
+| ✅ [Journeys](docs/spec/behavior/journeys.md) | [test/e2e/test_journeys.rb](test/e2e/test_journeys.rb) |

data/SECURITY.md

@@ -24,7 +24,7 @@ ask to stay anonymous.
 ## Scope
 
 In scope is anything that lets guest code cross the isolation boundary it should not:
-reaching host memory, the filesystem, the network, or `ENV`; obtaining ambient time or
+reaching host memory, the filesystem beyond what you mounted, the network, or `ENV`; obtaining ambient time or
 entropy the host froze; reaching a Service you never bound; or a
 memory-safety fault in the host codec or wasmtime driver.
 

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [0.19.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.18.0...kobako-runtime-v0.19.0) (2026-10-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* **runtime:** a struct literal no longer builds OpenOptions, Metadata, DirEntry, Snapshot, Capture, or Usage outside kobako-runtime; use their `new` or `Default` and assign each field.
+* the Guest ABI is version 5, so a Guest Binary built against version 4 is refused at Sandbox construction until rebuilt. The Yielder trait of kobako-runtime gains frame and takes the frame in yield_to_block; the Guest trait of kobako-core and the MrbGuest trait of kobako-mruby take the frame in yield_to_block; Downcall::Yield carries frame and args.
+* **runtime:** the Runtime trait's invoke takes the invocation's Grants as a fourth argument, so every engine implementing it must accept them.
+
+### Features
+
+* check what a rename moves as it moves, refusing a directory beneath a Policy ([23794bf](https://github.com/elct9620/kobako/commit/23794bfcb54e148126e29873fa9b52d9e3de8d8c))
+* **runtime:** bound the files and directories a Memory or Temporary holds ([8d0be0a](https://github.com/elct9620/kobako/commit/8d0be0ab3dc8c11bcb96865b0bf1a0bbb8dd3b16))
+* **runtime:** bound what a Memory or Temporary holds, 64 MiB by default ([2557d1b](https://github.com/elct9620/kobako/commit/2557d1ba7530aacfddf908aeddac561c4fbc5c8a))
+* **runtime:** draw every device a host does not name from one source ([210d55b](https://github.com/elct9620/kobako/commit/210d55b1b4e0699dc5ef56b4b6930be01658a3c6))
+* **runtime:** hand each invocation its Grants and let an engine declare the kinds it supports ([cba90ee](https://github.com/elct9620/kobako/commit/cba90eed09c8afcb23080cef1c9cbb3650648472)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** keep a directory descriptor's identity its own while open ([6267642](https://github.com/elct9620/kobako/commit/6267642ea831917be76a0101e8d206ccfa8834c1))
+* **runtime:** let a dispatch handler abandon its invocation ([179da9e](https://github.com/elct9620/kobako/commit/179da9ee1f31fed9e6d0c149faee0ad55f8db487))
+* **runtime:** let a Filesystem's file refuse its close ([af16007](https://github.com/elct9620/kobako/commit/af1600797b098796dd6f329672c7d04e2e1cd2fa)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** let a Mount decide its own access as the one kind of Grant ([5c9189e](https://github.com/elct9620/kobako/commit/5c9189eea8ac61cf165dca1b38e459c4f14acdd0)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** let a Mount's Policy judge the spelling the host stores ([5281057](https://github.com/elct9620/kobako/commit/52810573f22d2a3edfae9b34b7767a5f440fba15))
+* **runtime:** let the records a Filesystem or an engine builds gain fields ([c0ef88d](https://github.com/elct9620/kobako/commit/c0ef88d0b6df16d651e4c49226e41667307d772f))
+* **runtime:** name a file grown past what a Filesystem keeps ([7bac3e6](https://github.com/elct9620/kobako/commit/7bac3e65534097b85d93f5967b6c73a979869a78))
+* **runtime:** name each code a Filesystem may fail with ([1d980fa](https://github.com/elct9620/kobako/commit/1d980fa4328bad42e8a8665adfec9fc844690e97))
+* **runtime:** name the POSIX error each FilesystemError stands for ([01c301b](https://github.com/elct9620/kobako/commit/01c301b4af9f489594eb7a98ab48c508e5b61ca4))
+* **runtime:** refuse a Memory seed path through `..` ([b31434d](https://github.com/elct9620/kobako/commit/b31434d386ebde838c15755619c67da95311ecf6))
+* **runtime:** refuse a Mount at a path that is no absolute guest path ([a525758](https://github.com/elct9620/kobako/commit/a5257589f9d831b9a3b6d1952df6e5c8469630e1))
+* **runtime:** report a link a lookup does not follow as a link ([8c1e0b3](https://github.com/elct9620/kobako/commit/8c1e0b3e63fbc91b10f11cd91817ce94de24c7e6))
+* **runtime:** report the identity of what a path holds ([392bc0e](https://github.com/elct9620/kobako/commit/392bc0e9f2fb935934a0031bf7d64dec0b27df6a))
+* **runtime:** say whether a path beneath a Mount may pass a link ([7706a25](https://github.com/elct9620/kobako/commit/7706a2537bf8e5975b2b227bef0c05cb48c09f4b))
+* **runtime:** seed a Memory from a list that may not hold, answering why ([8ac2dfd](https://github.com/elct9620/kobako/commit/8ac2dfdf73b84fe2e53405a653d861ddca9ea98c))
+* **runtime:** ship the Memory, Temporary, Directory, and Overlay filesystems ([c60c453](https://github.com/elct9620/kobako/commit/c60c4535e966ffd501e03d7be7fef0a44d860b0b)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** stack an Overlay from Layers, each read-only or writable ([6c88188](https://github.com/elct9620/kobako/commit/6c88188cd7992c218f8c5a3be30981e685804078)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+
+
+### Bug Fixes
+
+* append through a Filesystem's file only in one step ([0509ca7](https://github.com/elct9620/kobako/commit/0509ca70d2d5a832303973ba0f7280be0731fd3d))
+* ask a mount's block once for a read ([f89bd16](https://github.com/elct9620/kobako/commit/f89bd16c1a71ed1d385ab9d3ac5974ac3f0a9103))
+* follow no link swapped in after a Policy judges a path ([ed93213](https://github.com/elct9620/kobako/commit/ed9321303dd45e113fc413e99e1240118cc4bbe4))
+* hold an Overlay's lock across each call, waiting without the GVL ([b8e7342](https://github.com/elct9620/kobako/commit/b8e734273fdc577a40be97c43c46d9548d66c625))
+* keep a link within the directory a descriptor opened ([952dd05](https://github.com/elct9620/kobako/commit/952dd0556969683f44798da94f9fc7a17c1f6d55))
+* run a stored block as the block of the Call that carried it ([bf33dc1](https://github.com/elct9620/kobako/commit/bf33dc1fd40c83498c6c12b0be52b3a835a144cf))
+* **runtime:** answer a host failure as the error naming it ([effd43a](https://github.com/elct9620/kobako/commit/effd43a85a3ba69aaa068d2c384c3b5cb466161c))
+* **runtime:** append to a Directory file in one host write ([4a5450a](https://github.com/elct9620/kobako/commit/4a5450a67e202e45299175c4fe7528cf50489f0e))
+* **runtime:** copy a file up whole when its Layer writes in parts ([89d87f7](https://github.com/elct9620/kobako/commit/89d87f7225611786467968ec34eba5a8223b5fc5))
+* **runtime:** fail an Overlay call a Layer cannot answer instead of guessing ([5ba0db3](https://github.com/elct9620/kobako/commit/5ba0db33c56ed837401bcb62345f81b4b50c317a))
+* **runtime:** hold each Memory entry under its own name ([8f1ba8a](https://github.com/elct9620/kobako/commit/8f1ba8a50d3d8ca3a695115d51b605be1f18e29e))
+* **runtime:** judge a link an Overlay's Layer holds as the link itself ([959c1f3](https://github.com/elct9620/kobako/commit/959c1f3dab6f6948baabbd914bbb86dfff090f7b))
+* **runtime:** keep an Overlay rename to one Layer and answer a landed change as done ([e3405b7](https://github.com/elct9620/kobako/commit/e3405b7139809ada202ffdb0d6bf1eef3dcbf056))
+* **runtime:** leave a Memory file as it was on a write of no bytes ([9f8fd23](https://github.com/elct9620/kobako/commit/9f8fd237b9b0042590b149f9b2051e0773d8b9af))
+* **runtime:** leave an Overlay unchanged when a removal or rename is refused ([a7bee4b](https://github.com/elct9620/kobako/commit/a7bee4b2a465a0ef0ad2e376c281dca82a0df0e1))
+* **runtime:** let a file or link in a Layer hide what lies below it ([fd579f6](https://github.com/elct9620/kobako/commit/fd579f679cfa8a83ec7d139066bc1a4570af398b))
+* **runtime:** make every Filesystem answer the methods that keep a guarantee ([00f5af6](https://github.com/elct9620/kobako/commit/00f5af63f34ac7722249746d0b0eb566da618803))
+* **runtime:** move a directory made again as the writable Layer's own ([ac3e864](https://github.com/elct9620/kobako/commit/ac3e864bbb0ce5d61def45e0403239be405481d3))
+* **runtime:** move a directory onto one that holds only markers ([934f0c3](https://github.com/elct9620/kobako/commit/934f0c39e0ad1189bdb1cb0461671245dea32f93))
+* **runtime:** open a Directory file the runtime neither reads nor writes ([6b30858](https://github.com/elct9620/kobako/commit/6b308583383d6803894b2c7af1a9ef05d72b0e7d)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** open a file already there without writing to create it ([7f76a1a](https://github.com/elct9620/kobako/commit/7f76a1af575739ae16c5daeb1df8268af44cea63))
+* **runtime:** panic on files a Memory cannot be seeded with ([cf5c835](https://github.com/elct9620/kobako/commit/cf5c835d7df8bf82972487280c6a6c79be955a68))
+* **runtime:** put an Overlay's markers back when the change fails ([78ddeed](https://github.com/elct9620/kobako/commit/78ddeeddda8b9f797a80ec3796b28e04cf99ffc9))
+* **runtime:** refuse a backslash in a Directory path on Windows ([88b5719](https://github.com/elct9620/kobako/commit/88b57195325b168395248a82b94a5ebf7e5f4142))
+* **runtime:** refuse a Directory append on Windows rather than take two steps ([a528cc9](https://github.com/elct9620/kobako/commit/a528cc9577f1b2e1359699e2400be93c1f3a9be7))
+* **runtime:** refuse a file moved beneath itself as no directory ([bfabb52](https://github.com/elct9620/kobako/commit/bfabb52b27080ee9e5000bd5524ea201a7e33d80))
+* **runtime:** refuse a host name that is not UTF-8 as an illegal sequence ([c4ff030](https://github.com/elct9620/kobako/commit/c4ff030ffa8e29fa1b10df4aaf6af65162c76353))
+* **runtime:** refuse a Memory file grown past what can be allocated ([302e2d4](https://github.com/elct9620/kobako/commit/302e2d4fcd5b31fee4e953e8993bb47d9a2a673a))
+* **runtime:** refuse an Overlay change landing beneath a read-only Layer ([e7b2f19](https://github.com/elct9620/kobako/commit/e7b2f19156df9773f669cbe8a7aaefc17591cca3))
+* **runtime:** refuse to open a FIFO, socket, or device beneath a Directory ([bdcaf78](https://github.com/elct9620/kobako/commit/bdcaf78bf131998648c65ac51ced4a588a79211f))
+* **runtime:** remove no directory as a file on any host ([c9c0820](https://github.com/elct9620/kobako/commit/c9c0820fd39c0744b9d9c367b977f6587d1f9589))
+* **runtime:** rename and copy up through an Overlay as overlayfs does ([ada5a86](https://github.com/elct9620/kobako/commit/ada5a86a8647d89666e9de808eb13ba638882e51))
+* **runtime:** replace neither a FIFO nor a directory with the other through an Overlay ([8fed062](https://github.com/elct9620/kobako/commit/8fed062438e105c6a784bf4bde1582fda9e3c9c2))
+* **runtime:** report a merged directory's identity alike through an Overlay's lstat ([ded3b4a](https://github.com/elct9620/kobako/commit/ded3b4aba78efa678318c38b139b5c9c76b5d3fd))
+* **runtime:** require cap-std 4.0.3 for the trailing-slash lookup fix ([549cfe0](https://github.com/elct9620/kobako/commit/549cfe07fc8b9affdc8a1765a9e4bc5963ef546e))
+* **runtime:** reserve an Overlay's marker name in any case ([ef39923](https://github.com/elct9620/kobako/commit/ef399230eabe01ad6eed632b2753880ae1fc322c))
+* **runtime:** reserve exactly what a Memory file grows by ([96f8141](https://github.com/elct9620/kobako/commit/96f8141442cac2170a8bf8a76055d4f4659b1100))
+* **runtime:** spell a Directory path's last name without following a link there ([c5e5ae7](https://github.com/elct9620/kobako/commit/c5e5ae74ec1f6ee07e24da08d7b097fb6a882961))
+* **runtime:** spell a path on XFS by listing rather than trusting exact names ([f89495d](https://github.com/elct9620/kobako/commit/f89495dcfd7c6d05d46ebc5dbae0039856cc15c6))
+* **wasmtime:** hold the whole invocation to its deadline ([231e325](https://github.com/elct9620/kobako/commit/231e32592699008adf3105050bee8b5528ea27a8))
+* **wasmtime:** place an append at the end as the file stands when it lands ([d7291c4](https://github.com/elct9620/kobako/commit/d7291c4f32fb1f5f2494c69c76796476bbcf4d43))
+* **wasmtime:** refuse a link an open asks not to follow ([123a01b](https://github.com/elct9620/kobako/commit/123a01b01f59cc69c0e3a23f9aeb01aa89132c07))
+
+
+### Performance Improvements
+
+* **runtime:** list an Overlay directory in time linear to its entries ([be3f446](https://github.com/elct9620/kobako/commit/be3f446f782cbd72b114f7b6072e3b50c391f093))
+* **runtime:** stop an Overlay's marker lookup at a directory a Layer lacks ([494fa09](https://github.com/elct9620/kobako/commit/494fa090e90806c50e4e8baaa4f1001efc388b45))
+
 ## [0.18.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.17.0...kobako-runtime-v0.18.0) (2026-10-13)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -2,10 +2,12 @@
 #
 # The contract a wasm engine must satisfy to drive a kobako guest,
 # free of any engine or frontend type: the `Runtime` trait plus the
-# neutral value types (`Snapshot`, `Trap`, `SetupError`, ...) and the
-# dispatch / yield re-entry traits a frontend supplies. Engine
-# implementations (`kobako-wasmtime`) and host frontends (the Ruby
-# ext) meet on this surface, so the engine stays swappable.
+# neutral value types (`Snapshot`, `Trap`, `SetupError`, ...), the
+# dispatch / yield re-entry traits a frontend supplies, and the Grants
+# a frontend hands each invocation, the Mount and the Filesystems it
+# places. Engine implementations (`kobako-wasmtime`) and host frontends
+# (the Ruby ext) meet on this surface, so the engine stays swappable.
+# `cap-std` confines the Directory Filesystem to its host directory.
 #
 # Self-contained by design: the Ruby gem ships this crate without the
 # `crates/` workspace manifest, so no `workspace = true` inheritance
@@ -13,7 +15,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.18.0"
+version = "0.19.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -27,4 +29,23 @@ categories = ["wasm", "virtualization"]
 # in-tree builds (and the Ruby gem, which ships both crates) resolving
 # locally.
 [dependencies]
-kobako-transport = { version = "0.18.0", path = "../kobako-transport" }
+kobako-transport = { version = "0.19.0", path = "../kobako-transport" }
+# cap-std resolves every path of the Directory Filesystem beneath its host
+# directory, refusing a `..` or a symbolic link that would lead out of it.
+# 4.0.3 is the first release whose trailing-slash lookup keeps that
+# refusal (GHSA-hp8f-xmx4-4qrg).
+cap-std = "4.0.3"
+# cap-fs-ext opens a Directory's path one directory at a time without
+# following a link, so a Mount's Policy judges the path its call reaches.
+cap-fs-ext = "4.0.3"
+
+# rustix switches a Directory file to append mode for one write, so the
+# host places it at the file's end in one step; std cannot set file flags.
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1.1.4", features = ["fs"] }
+
+# libc asks macOS for the name a directory stores, which a Mount's Policy
+# judges in place of a spelling the host folds; rustix has no
+# getattrlist.
+[target.'cfg(target_os = "macos")'.dependencies]
+libc = "0.2.191"

data/crates/kobako-runtime/README.md

@@ -4,9 +4,9 @@ Engine-neutral host runtime contract for
 [kobako](https://github.com/elct9620/kobako), an in-process Wasm
 sandbox for running untrusted mruby scripts.
 
-A kobako host drives a Guest Binary through a wasm engine; this crate
-is the surface where the two meet, free of any engine or frontend
-type, so the engine stays swappable.
+A kobako host drives a Guest Binary through a wasm engine. This crate
+is where the two meet, free of any engine or frontend type, so the
+engine stays swappable.
 
 | Module | What it declares |
 |---|---|
@@ -14,19 +14,24 @@ type, so the engine stays swappable.
 | `snapshot` | each invocation's `Completion` (outcome or trap), both output `Capture`s, and `Usage` |
 | `error` | the neutral failure types: `Trap`, `SetupError`, and `InvokeError` over both |
 | `profile` | the isolation `Profile` a runtime declares |
+| `grant` | the `Grant` a frontend hands each invocation, and the `GrantKind`s a runtime supports |
+| `mount` | the `Mount` at a guest path, and the `Policy` judging its paths |
+| `filesystem` | the `Filesystem` trait, its `Access`, and the four kinds kobako ships |
 | `dispatch` / `yielder` | the `DispatchHandler` and `Yielder` traits a frontend supplies for guest→host dispatch and block-yield re-entry |
 
-Engine implementations (such as `kobako-wasmtime`) implement
-`Runtime`; host frontends (such as the kobako Ruby gem's native ext)
-map the neutral types onto their own language surface.
+Engine implementations such as `kobako-wasmtime` implement `Runtime`.
+Host frontends such as the kobako Ruby gem's native ext map the neutral
+types onto their own language surface.
 
 ## Usage
 
+Add the crate to an engine or a frontend that speaks the contract.
+
 ```toml
 [dependencies]
-kobako-runtime = "0.18.0" # x-release-please-version
+kobako-runtime = "0.19.0" # x-release-please-version
 ```
 
 ## License
 
-Apache-2.0
+Licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

data/crates/kobako-runtime/src/dispatch.rs

@@ -25,4 +25,12 @@ use kobako_transport::envelope::{Call, Reply};
 /// the payload onward without copying it first.
 pub trait DispatchHandler: Send + Sync {
     fn dispatch(&self, call: Call<'_>, yielder: &mut dyn Yielder) -> Option<Reply>;
+
+    /// Whether the host gave up on this invocation, as when one of its
+    /// callbacks raised something meant for the host rather than the
+    /// guest. The engine ends the invocation at the next host call it
+    /// answers, so the guest cannot go on as if it had been answered.
+    fn abandoned(&self) -> bool {
+        false
+    }
 }