security_box 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdcc33a7689dd5d68b5e9ca6c8cd36a83d8da9aa5a44c9b29a5994bd991c5d9e
-  data.tar.gz: a2f4fbf283527b9fcf484a9dc06adb3a5d34d2a1c97f355412a880c5204c9283
+  metadata.gz: 6c7d1c1387ec5b1dffdb9781552e489d4b3d45e7066fdd3c7932e6ba39a8432f
+  data.tar.gz: 7770652a22e98d5067c851b5a1c790896b986b6dc7a68ca03ea4a0c3c4bb2110
 SHA512:
-  metadata.gz: 86158b7097c7e53602f80949350d2f2aebaf9f672400f908127fb995fbf829dc5a16928873231d1c2b8539660a0f7c5a0c2f600f40a225558afaf39f83a9ee77
-  data.tar.gz: e08ee261ac36c91b3fe6761a01e655410d60c3023094e852c7e1fa9ddc8728efe646366bd840c6863264b1f41826874794b52e6a1125dddbca8f662ae3f76fe4
+  metadata.gz: 2d4f7f357bc27692a392251edfd887c310f94f6b0e5f47dccd01c9ea420c427f307888791205d82ee54a12ad117351464b6deefc06211cdabcf6c2bdeb86779e
+  data.tar.gz: b61989d1e43f6f801b1522643239a96118128825837f680bc57122ea8874be4f6229bde01c8af81f53bcbc8d9985e3100f329e2bcbc56797067d6584ed58cca8

data/CHANGELOG.md

@@ -5,6 +5,111 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-20
+
+### Added
+
+- Folder mounts (read-only by default): `c.mount "host/path" => "/data"` in the
+  register DSL (or `mounts:` in `Configuration.build`), with `c.mount_rw` for an
+  opt-in writable mount. Guest code can read a mounted host directory
+  (`File.read`, `Dir[]`, `File.open`); write attempts into a read-only mount fail
+  guest-side with `Errno::EPERM` and leave the host directory untouched.
+- `Configuration#mounts`: a frozen array of frozen `{host:, guest:, mode:}` hashes.
+  Mounts are config values — they flow through `#with`, `#fingerprint` (equal
+  mounts → equal fingerprint) and RactorPool requests. Relative host paths are
+  expanded against `Dir.pwd` at DSL time.
+- Mount validation (`SecurityBox::InvalidConfiguration` on violation): mode must be
+  `:read_only`/`:read_write` (wasmtime silently accepts unknown symbols, so the mode
+  is never trusted to the runtime); guest paths must be absolute and normalized
+  (no `..`, no trailing `/`, not `/`); guest paths must not overlap the reserved
+  `/work`, `/usr` or `/src` trees (exact or nested — a collision with the embedded
+  VFS is silently shadowed, a mount inside `/usr` breaks the guest boot, and inside
+  `/work` it would create a read-only subtree); duplicate guest paths are rejected
+  (wasmtime's last-mount-wins is silently surprising); at most 16 mounts.
+- Per-eval host-path validation: a mount whose host directory vanished returns a
+  `:sandbox_error` Result with a `security_box:` note instead of raising
+  `Wasmtime::Error` out of `#eval` (the store creation now also sits inside the
+  eval's rescue, so wasmtime setup failures can never raise).
+
+### Changed
+
+- `Sandbox#eval` (and pool equivalents) accept `mounts:` as a per-call override
+  (replaces the configuration's mounts, like `env:`).
+- README: new "Folder mounts" section + updated isolation matrix and defense notes
+  (a mounted folder's content is fully readable by guest code).
+
+### Investigation (no change needed, documented)
+
+- Q6 probe (stage 5): the embedded VFS is **not** guest-writable (`File.write`
+  into `/usr`, `/src` or `/` fails with `Errno::ENOENT`; deletes with `ENOTSUP`),
+  so no prelude File-write restriction is warranted; WASI remains the primary
+  enforcement. Symlink escapes from a mounted directory are blocked by wasmtime
+  (`Errno::EPERM`); the guest cannot even create symlinks. Measured mount cost:
+  none (warm-boot p50 ~260ms with 0/1/4/8 mounts). Evidence and probes in
+  `docs/plan/stages/stage_5.md` and `bin/spike_stage5_mounts.rb`.
+
+## [0.4.0] - 2026-09-15
+
+### Added
+
+- `SecurityBox::Pool` (`SecurityBox.pool`): a bounded pool of `:oneshot` sandboxes —
+  hard cap on concurrent evals (`size:`), sandbox reuse, `checkout` block and metrics
+  (`created`/`evals`/`total_ms`/`avg_ms`). Evals serialize on the GVL (documented).
+- `SecurityBox::RactorPool` (`SecurityBox.ractor_pool`): real parallelism — worker
+  Ractors sharing one Ractor-shareable Engine + compiled Module (stage-3 "Plan C").
+  Measured ≈0.52–0.53 parallel/serial wall ratio at 4 workers on 6 cores (~1.9x),
+  RSS ≈57MB; per-call overrides, statuses and trap recovery behave like
+  `Sandbox#eval`; a dead worker degrades to a `:sandbox_error` Result instead of a
+  hang.
+- `Configuration#fuel_ms`: rate-based fuel budgeting (~4e6 fuel/ms from the stage-3
+  calibration table + ~1e9 boot allowance), exposed via `Configuration#effective_fuel`
+  and usable per call. `fuel` and `fuel_ms` are mutually exclusive in the builder DSL
+  and in `#with`; switch back with `with(fuel_ms: nil, fuel: ...)`.
+- `docs/plan/stages/stage_4.md` with the worker-mode feasibility investigation.
+
+### Changed
+
+- The eval core was extracted from `Sandbox` into `SecurityBox::EvalRun` (shared by
+  `Sandbox` and `RactorPool` workers); `Sandbox` is now a thin, thread-safe wrapper.
+- README: the "Ractor note" roadmap item is delivered; concurrency guidance rewritten
+  around `Pool`/`RactorPool`.
+
+### Investigation (negative result, documented)
+
+- `:worker` mode (long-lived instance amortizing the ~240ms boot) is infeasible on
+  wasmtime-rb 48 (sync WASI): `invoke` holds the GVL during compute *and* while the
+  guest is blocked on a WASI read; epoch deadlines never fire inside a blocking
+  syscall; and per-request limits would require mutating a live Store from another
+  thread (unsafe). Evidence and probes in `docs/plan/stages/stage_4.md` and
+  `bin/spike_stage4_worker.rb`.
+
+## [0.3.0] - 2026-09-14
+
+### Added
+
+- Named, reusable profiles: `SecurityBox.register(:name, from: :base) { |c| c.fuel 100 }`
+  and `SecurityBox.spawn(:name, **overrides)` (a `Configuration` or the defaults also
+  work). Profiles are immutable; duplicate/unknown names raise
+  `SecurityBox::InvalidConfiguration`.
+- `SecurityBox::Configuration#fingerprint`: a stable identity for equal settings
+  (SHA-256 of the canonical configuration), ready for artifact caches.
+- Guest error envelopes now carry a `backtrace`: user frames only, capped at 20,
+  sandbox-internal locations (no host paths). Surfaced via `Result#error["backtrace"]`;
+  malformed backtraces invalidate the envelope (`:sandbox_error`).
+- `Result#fuel_used` is now `nil` for `:timeout`: epoch traps restore fuel to the last
+  checkpoint, so the restored value understated consumption by orders of magnitude.
+  (Truthful on completion, fuel exhaustion and memory-limit traps.)
+
+### Changed
+
+- A guest `NoMemoryError` (interpreter OOM against the store limit) is reported as
+  `:memory_limit` instead of `:error`.
+- A `memory_size` below the image's declared minimum (1528 pages ≈ 95.5 MiB) now
+  returns a `:sandbox_error` Result with a `security_box:` note on stderr instead of
+  raising `Wasmtime::Error` out of `#eval`.
+- The sandbox image must be repacked (`rake security_box:build_image`) when
+  upgrading: the guest entrypoint protocol changed.
+
 ## [0.2.0] - 2026-09-14
 
 ### Added

data/README.md

@@ -119,7 +119,8 @@ sandbox.eval("3 * 3").value # => 9
 ### Per-call limits
 
 Options can be passed per call (derived from the configuration without mutating it):
-`timeout_ms`, `fuel`, `memory_size`, `stdout_limit`, `stderr_limit`.
+`timeout_ms`, `fuel`, `fuel_ms`, `memory_size`, `stdout_limit`, `stderr_limit`,
+`mounts`.
 
 ```ruby
 # Wall-clock limit via epoch interruption
@@ -144,13 +145,87 @@ SecurityBox.eval('1000.times { print "x" * 1000 }', stdout_limit: 4096).stdout.b
 Exceptions raised by guest code are a *result*, not a sandbox failure:
 
 ```ruby
-result = SecurityBox.eval('raise ArgumentError, "boom"')
+result = SecurityBox.eval("def boom; raise ArgumentError, 'boom'; end; boom")
 
-result.status           # => :error
-result.error["class"]   # => "ArgumentError"
-result.error["message"] # => "boom"
+result.status                    # => :error
+result.error["class"]            # => "ArgumentError"
+result.error["message"]          # => "boom"
+result.error["backtrace"]        # => ["sandbox:1:in 'Object#boom'", "sandbox:1:in '<main>'"]
 ```
 
+The backtrace contains guest frames only (sandbox-internal locations, capped at
+20 frames) — nothing from the host filesystem leaks.
+
+### Named profiles
+
+Reusable configurations registered once and spawned as often as needed:
+
+```ruby
+SecurityBox.register(:default) do |c|
+  c.fuel 10_000_000_000
+  c.timeout_ms 2_000
+end
+
+SecurityBox.register(:lean, from: :default) do |c|
+  c.fuel 2_000_000_000        # boot alone costs ~1e9; see the fuel notes below
+  c.timeout_ms 500
+end
+
+box = SecurityBox.spawn(:lean)               # Sandbox from the profile
+box.eval("40 + 2").value                     # => 42
+
+SecurityBox.spawn(:lean, timeout_ms: 100)    # per-call override (profile unchanged)
+SecurityBox.spawn                            # default configuration
+```
+
+Profiles are immutable: duplicate names and unknown names raise
+`SecurityBox::InvalidConfiguration`; overrides never mutate the profile.
+`SecurityBox::Configuration#fingerprint` gives every configuration a stable
+identity (equal settings → equal fingerprint), used to share runtime artifacts.
+
+### Folder mounts
+
+Host folders can be mounted into the sandbox explicitly. **Mounts are read-only
+by default**; `mount_rw` is the opt-in writable form:
+
+```ruby
+SecurityBox.register(:reader) do |c|
+  c.mount    "./data" => "/data"   # read-only (host path expanded at DSL time)
+  c.mount_rw "./state" => "/state" # opt-in writable
+end
+
+box = SecurityBox.spawn(:reader)
+box.eval('File.read("/data/input.csv")')      # guest reads mounted content
+box.eval('File.write("/state/last.txt", Time.now.to_i)')
+
+# Per-call override (replaces the configuration's mounts, like env:)
+SecurityBox.eval('File.read("/data/a.txt")',
+                 mounts: [{ host: "./data", guest: "/data", mode: :read_only }])
+```
+
+Rules (violations raise `SecurityBox::InvalidConfiguration` at registration):
+
+- A mount is one `{host:, guest:, mode:}` pair; `mode` is `:read_only` or
+  `:read_write` and the DSL defaults to read-only.
+- Guest paths must be absolute and normalized, must not overlap the reserved
+  `/work` (sandbox tmpdir), `/usr` (embedded stdlib) or `/src` (entrypoint)
+  trees — exact or nested — and must be unique.
+- At most 16 mounts per configuration.
+- The host path must exist and be a directory at eval time; otherwise the eval
+  returns `:sandbox_error` with a `security_box:` note on stderr (instead of
+  raising).
+
+Security notes:
+
+- **A mounted folder's content is fully readable by guest code** — only mount
+  directories whose content you are willing to expose to the executed code.
+- Read-only mounts are enforced by wasmtime: writes fail guest-side with
+  `Errno::EPERM` and the host directory is never touched. Symlinks inside a
+  mounted directory cannot escape it (wasmtime caps path resolution at the
+  preopen root), and guest code cannot create symlinks at all.
+- Mounted content can also be **written by the guest** in `mount_rw` mounts —
+  treat a writable mount as part of the guest's blast radius.
+
 ### Configuration
 
 `SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
@@ -158,12 +233,14 @@ result.error["message"] # => "boom"
 ```ruby
 config = SecurityBox::Configuration.build(
   fuel: 10_000_000_000,             # deterministic CPU budget
+  fuel_ms: nil,                     # or a millisecond-based budget (mutually exclusive with fuel)
   timeout_ms: 2_000,                # wall-clock limit (epoch interruption)
   memory_size: 512 * 1024 * 1024,   # wasm linear memory limit
   stdout_limit: 1 << 20,            # stdout capture capacity in bytes
   stderr_limit: 1 << 16,            # stderr capture capacity in bytes
   epoch_interval_ms: 25,            # epoch timer granularity
-  env: { "LANG" => "C" }            # guest environment (empty by default)
+  env: { "LANG" => "C" },           # guest environment (empty by default)
+  mounts: []                        # host-folder mounts (see "Folder mounts")
 )
 
 lean = config.with(timeout_ms: 500, fuel: 5_000_000)
@@ -175,11 +252,11 @@ sandbox = SecurityBox::Sandbox.new(lean)
 | Status | Meaning |
 |---|---|
 | `:ok` | guest code ran and returned a value |
-| `:error` | guest code raised an exception (see `#error`) |
-| `:timeout` | interrupted by the epoch deadline (wall clock) |
+| `:error` | guest code raised an exception (see `#error`; includes `backtrace`) |
+| `:timeout` | interrupted by the epoch deadline (wall clock); `fuel_used` is `nil` (epoch traps restore fuel to the checkpoint) |
 | `:fuel_exhausted` | CPU budget exhausted |
-| `:memory_limit` | exceeded the store `memory_size` |
-| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope) |
+| `:memory_limit` | exceeded the store `memory_size` (wasm trap or guest `NoMemoryError`) |
+| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope, `memory_size` below the image's minimum) |
 
 Values are JSON-serialized; non-serializable objects are returned as their `inspect`
 string.
@@ -190,6 +267,8 @@ string.
 |---|---|
 | `File.write("/etc/passwd", ...)` | `Errno::ENOENT` (guest does not see the host FS) |
 | `Dir["/*"]` | `[]` (empty root) |
+| `File.write` into a read-only mount | `Errno::EPERM` (wasmtime-enforced; host dir untouched) |
+| symlink escape from a mounted directory | `Errno::EPERM` (path resolution capped at the preopen root) |
 | `system("ls")` / backticks / `IO.popen` / `Process.spawn` | `SecurityError` (hardening prelude) |
 | `Kernel#open(...)` | `SecurityError` (pipe form; use `File.open`) |
 | `fork` | `NotImplementedError` |
@@ -202,9 +281,74 @@ string.
 Notes:
 
 - The guest Ruby version is the one from ruby.wasm (4.0), not necessarily the host's.
-- Concurrency: `invoke` holds the GVL, so executions serialize per host process. Scale
-  horizontally with multiple processes (e.g., Puma workers); a stuck guest still can't
-  hang the process thanks to the epoch deadline.
+- Mounts widen the trust surface: a mounted folder's content is fully readable by
+  guest code (see "Folder mounts" above). Read-only by default; nothing outside
+  `/work` is writable without an explicit `mount_rw`.
+- Concurrency: `invoke` holds the GVL, so executions on threads serialize — use
+  `RactorPool` (below) for parallelism inside one process, or scale horizontally with
+  multiple processes (e.g., Puma workers). A stuck guest still can't hang the process
+  thanks to the epoch deadline.
+- Ractor: wasmtime `Engine`/`Module` are Ractor-shareable and Ractors run wasm in
+  parallel — measured ≈1.9x wall-time speedup at 4 workers on 6 cores through
+  `RactorPool` (see `docs/plan/stages/stage_3.md` and `stage_4.md`).
+- Memory: the packed image declares a 1528-page (~95.5 MiB) minimum; `memory_size`
+  below that fails instantiation (reported as `:sandbox_error`). Practical minimum is
+  ~128–144MB for small workloads; the 512MB default leaves comfortable headroom.
+- Fuel budgeting: compute workloads burn ~4–8e9 fuel/s (tight loops up to ~8.4e9/s)
+  and every eval costs ~1e9 fuel for boot — see the calibration table in
+  `docs/plan/stages/stage_3.md`. Consequently `fuel` below ~1e9 cannot even boot, and
+  `timeout_ms` below ~300ms times out during the guest boot (~500ms is a practical
+  floor). Prefer thinking in milliseconds? Use `fuel_ms` (below).
+
+## Concurrency
+
+Two pools are available, with honestly different guarantees (measured in stage 4 —
+`invoke` holds the GVL, so a long-lived `:worker` instance is impossible on the current
+wasmtime-rb; one wasm boot per eval stays on the hot path):
+
+### `Pool` — bounded concurrency on threads
+
+```ruby
+pool = SecurityBox.pool(:lean, size: 4)
+pool.eval("40 + 2").value    # => 42
+pool.checkout { |sandbox| sandbox.eval("1 + 1") }
+pool.metrics                 # => {size:, created:, evals:, total_ms:, avg_ms:}
+pool.shutdown
+```
+
+Caps concurrent evals at `size` and reuses sandbox objects, but evals serialize on the
+GVL — one at a time.
+
+### `RactorPool` — real parallelism
+
+```ruby
+pool = SecurityBox.ractor_pool(:lean, size: 4)
+pool.eval("40 + 2").value    # => 42
+pool.shutdown
+```
+
+Worker Ractors share one Engine + compiled Module and run wasm truly in parallel
+(~1.9x wall-time speedup at 4 workers on 6 cores; measured ≈0.53 parallel/serial wall
+ratio across 1M–4M-iteration workloads). Per-call overrides, user errors, timeouts and
+fuel exhaustion behave exactly like `Sandbox#eval`, and the worker survives traps and
+keeps serving. Costs one module deserialize at creation (~0.5s via the disk cache);
+each eval still pays the ~240ms guest boot.
+
+### `fuel_ms` — rate-based fuel budgeting
+
+Instead of counting raw fuel, budget approximate wall-time of compute:
+
+```ruby
+config = SecurityBox::Configuration.build(fuel_ms: 100) # ≈100ms of compute + boot allowance
+SecurityBox.spawn(config).eval("i = 0; while i < 5_000_000; i += 1; end").status
+# => :fuel_exhausted (5M tight iterations ≈ 2.4e9 fuel > the 100ms budget)
+```
+
+`fuel_ms` converts to fuel with the conservative stage-3 calibration rate
+(4e6 fuel/ms ≈ 4e9 fuel/s) plus a ~1e9 boot allowance (`Configuration#effective_fuel`).
+The epoch `timeout_ms` remains the mandatory wall-clock backstop. `fuel` and `fuel_ms`
+are mutually exclusive in the builder DSL and in `#with` overrides; a `fuel_ms`
+configuration can be switched back with `with(fuel_ms: nil, fuel: ...)`.
 
 ## Running the tests
 
@@ -240,3 +384,9 @@ bundle exec ruby bin/spike.rb
 - `docs/plan/stages/stage_1.md` — stage 1 findings and measured numbers
 - `docs/plan/stages/stage_2.md` — stage 2 findings (hardening prelude, result-channel
   integrity, compiled-module disk cache)
+- `docs/plan/stages/stage_3.md` — stage 3 findings (named profiles, Ractor
+  parallelism, memory floor, fuel calibration, backtrace)
+- `docs/plan/stages/stage_4.md` — stage 4 findings (worker-mode feasibility, pools,
+  `fuel_ms`)
+- `docs/plan/stages/stage_5.md` — stage 5 findings (folder mounts: read-only
+  enforcement, reserved-path collisions, symlink escapes, mount cost)

data/lib/security_box/assets/security_box.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/security_box/assets/security_box.wasm
-size: 115876739 bytes
-sha256: 335531ec6194a2bae2f94f6d0d24188c3f2f15b00cd1bda4a1e2460bb033e1e0
+size: 115877509 bytes
+sha256: d7af08b7b11f5ac8bf9b4b8e9cb2ac6ca3e5c977f0dcdfea3551627247589a70

data/lib/security_box/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "digest"
+require "json"
+
 module SecurityBox
   # Immutable sandbox configuration. Use .build to create and #with to derive.
   class Configuration
@@ -10,35 +13,70 @@ module SecurityBox
     DEFAULTS = {
       image_path: nil, # resolved dynamically (project's build/security_box.wasm)
       fuel: 10_000_000_000,
+      fuel_ms: nil, # rate-based fuel ergonomics (see FUEL_PER_MS); nil = use :fuel
       timeout_ms: 2_000,
       memory_size: 512 * 1024 * 1024,
       stdout_limit: 1 << 20,
       stderr_limit: 1 << 16,
       epoch_interval_ms: 25,
-      env: {}.freeze
+      env: {}.freeze,
+      mounts: [].freeze
     }.freeze
 
-    attr_reader :image_path, :fuel, :timeout_ms, :memory_size,
-                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env
+    # Fuel-per-ms conversion for #fuel_ms, from the stage-3 calibration table
+    # (docs/plan/stages/stage_3.md): compute workloads burn 3.2e9–8.4e9 fuel/s;
+    # 4e9/s is the conservative floor. The guest boot baseline (~9.1e8 fuel)
+    # is added on top so the budget covers boot even for trivial evals.
+    FUEL_PER_MS = 4_000_000
+    BOOT_FUEL_ALLOWANCE = 1_000_000_000
+
+    attr_reader :image_path, :fuel, :fuel_ms, :timeout_ms, :memory_size,
+                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env, :mounts
 
     def self.build(**options)
       new(**DEFAULTS.merge(options)).freeze
     end
 
-    def initialize(image_path: nil, fuel:, timeout_ms:, memory_size:,
-                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:)
+    def initialize(image_path: nil, fuel:, fuel_ms:, timeout_ms:, memory_size:,
+                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:, mounts:)
       @image_path = image_path || default_image_path
       @fuel = Integer(fuel)
+      @fuel_ms = fuel_ms.nil? ? nil : Integer(fuel_ms)
       @timeout_ms = Integer(timeout_ms)
       @memory_size = Integer(memory_size)
       @stdout_limit = Integer(stdout_limit)
       @stderr_limit = Integer(stderr_limit)
       @epoch_interval_ms = Integer(epoch_interval_ms)
       @env = env.freeze
+      @mounts = Mounts.normalize(mounts)
       freeze
     end
 
+    # The fuel budget actually applied to each evaluation. When :fuel_ms is
+    # set it takes precedence: an approximate millisecond-based budget
+    # (fuel_ms × FUEL_PER_MS + boot allowance) instead of a raw fuel count.
+    # The epoch timeout remains the mandatory wall-clock backstop either way.
+    def effective_fuel
+      return fuel unless fuel_ms
+
+      fuel_ms * FUEL_PER_MS + BOOT_FUEL_ALLOWANCE
+    end
+
+    # Derives a copy with `changes` applied (never mutates the receiver).
+    # Passing both :fuel and a non-nil :fuel_ms is ambiguous and rejected;
+    # overriding :fuel on a configuration that uses :fuel_ms is rejected too
+    # (pass fuel_ms: nil first to switch to a raw fuel budget).
     def with(**changes)
+      if changes.key?(:fuel_ms)
+        if changes[:fuel_ms] && changes.key?(:fuel)
+          raise InvalidConfiguration,
+                "fuel and fuel_ms are mutually exclusive overrides"
+        end
+      elsif changes.key?(:fuel) && @fuel_ms
+        raise InvalidConfiguration,
+              "configuration uses fuel_ms (#{fuel_ms}); override fuel_ms or clear it with fuel_ms: nil instead of fuel"
+      end
+
       self.class.build(**to_h.merge(changes))
     end
 
@@ -46,15 +84,112 @@ module SecurityBox
       {
         image_path: @image_path,
         fuel: @fuel,
+        fuel_ms: @fuel_ms,
         timeout_ms: @timeout_ms,
         memory_size: @memory_size,
         stdout_limit: @stdout_limit,
         stderr_limit: @stderr_limit,
         epoch_interval_ms: @epoch_interval_ms,
-        env: @env
+        env: @env,
+        mounts: @mounts
       }
     end
 
+    # Stable identity of the configuration values (SHA-256 of the normalized
+    # hash). Two configurations with equal settings — regardless of how they
+    # were built — share the same fingerprint; any #with change produces a
+    # different one. Used to key profiles and, later, cached artifacts.
+    def fingerprint
+      Digest::SHA256.hexdigest(JSON.generate(canonical))
+    end
+
+    def canonical
+      to_h.merge(env: @env.sort.to_h)
+    end
+
+    # Mutable collector for the register DSL. Setter names match the
+    # Configuration options (no `=`, e.g. `c.fuel 100`); only changed values
+    # are collected and merged over the base profile.
+    class Builder
+      def initialize
+        @changes = {}
+      end
+
+      def changes
+        @changes
+      end
+
+      def image_path(value)
+        @changes[:image_path] = value
+      end
+
+      def fuel(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel_ms)
+
+        @changes[:fuel] = value
+      end
+
+      # Rate-based fuel ergonomics: sets fuel from an approximate millisecond
+      # budget (see Configuration#effective_fuel). Mutually exclusive with
+      # an explicit :fuel.
+      def fuel_ms(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel)
+
+        @changes[:fuel_ms] = value
+      end
+
+      def timeout_ms(value)
+        @changes[:timeout_ms] = value
+      end
+
+      def memory_size(value)
+        @changes[:memory_size] = value
+      end
+
+      def stdout_limit(value)
+        @changes[:stdout_limit] = value
+      end
+
+      def stderr_limit(value)
+        @changes[:stderr_limit] = value
+      end
+
+      def epoch_interval_ms(value)
+        @changes[:epoch_interval_ms] = value
+      end
+
+      # Replaces the guest environment (it is not merged with the base).
+      def env(value)
+        @changes[:env] = value
+      end
+
+      # Mounts a host directory into the guest, read-only by default:
+      #   c.mount "host/path" => "/data"
+      # Each call appends one mount; use #mount_rw for a writable mount.
+      def mount(mapping)
+        add_mount(mapping, :read_only)
+      end
+
+      # Opt-in writable mount — the only way to expose a writable host path
+      # besides the sandbox-private /work tmpdir:
+      #   c.mount_rw "host/path" => "/data"
+      def mount_rw(mapping)
+        add_mount(mapping, :read_write)
+      end
+
+      private
+
+      def add_mount(mapping, mode)
+        unless mapping.is_a?(Hash) && mapping.size == 1
+          raise InvalidConfiguration,
+                'mount expects exactly one pair: c.mount "host/path" => "/data"'
+        end
+
+        host, guest = mapping.first
+        @changes[:mounts] = Array(@changes[:mounts]) + [{ host: host, guest: guest, mode: mode }]
+      end
+    end
+
     private
 
     # Resolution order (first existing path wins):
@@ -74,4 +209,117 @@ module SecurityBox
             "or pass image_path in the configuration."
     end
   end
+
+  # Validated collection of host-folder mounts (stage 5). A mount is a frozen
+  # {host:, guest:, mode:} hash; `mounts` in a Configuration is a frozen array
+  # of these, so the value survives #with, #fingerprint and Ractor ports.
+  #
+  # Validation (InvalidConfiguration on any violation):
+  #   - mode is :read_only or :read_write (wasmtime silently accepts unknown
+  #     symbols, so the mode is checked here, never trusted to the runtime)
+  #   - host: non-empty string; relative paths are expanded against Dir.pwd
+  #     (existence/directory checks are per-eval, in EvalRun — dirs can vanish)
+  #   - guest: absolute, normalized path (no "..", no trailing slash), not "/"
+  #   - guest paths must not overlap /work, /usr or /src (exact or nested):
+  #     a collision with the embedded VFS is silently shadowed (stage-5 spike:
+  #     the mount content is invisible), a mount inside /usr even breaks the
+  #     guest boot, and inside /work it would create a read-only subtree
+  #   - duplicate guest paths are rejected (wasmtime's last-mount-wins is
+  #     silently surprising)
+  #   - at most MAX_MOUNTS mounts
+  module Mounts
+    MODES = %i[read_only read_write].freeze
+    RESERVED_GUEST_PATHS = %w[/work /usr /src].freeze
+    MAX_MOUNTS = 16
+
+    class << self
+      # Validates + normalizes `raw` (an array of {host:, guest:, mode:} hashes
+      # or nil) and returns a frozen array of frozen, normalized hashes.
+      def normalize(raw)
+        return [].freeze if raw.nil?
+
+        raise InvalidConfiguration,
+              "mounts must be an Array of {host:, guest:, mode:} hashes, got #{raw.class}" unless raw.is_a?(Array)
+
+        mounts = raw.map { |entry| normalize_entry(entry) }
+        check_duplicates(mounts)
+        check_reserved(mounts)
+        check_count(mounts)
+        mounts.freeze
+      end
+
+      private
+
+      def normalize_entry(entry)
+        unless entry.is_a?(Hash) && entry.keys.sort == %i[guest host mode]
+          raise InvalidConfiguration,
+                "each mount must be a Hash with exactly :host, :guest and :mode keys, got #{entry.inspect}"
+        end
+
+        mode = entry[:mode]
+        unless MODES.include?(mode)
+          raise InvalidConfiguration,
+                "mount mode must be one of #{MODES.map(&:inspect).join(' or ')}, got #{mode.inspect}"
+        end
+
+        { host: normalize_host(entry[:host]),
+          guest: normalize_guest(entry[:guest]),
+          mode: mode }.freeze
+      end
+
+      def normalize_host(host)
+        unless host.is_a?(String) && !host.empty?
+          raise InvalidConfiguration, "mount host path must be a non-empty String, got #{host.inspect}"
+        end
+
+        File.expand_path(host).freeze
+      end
+
+      def normalize_guest(guest)
+        unless guest.is_a?(String) && !guest.empty?
+          raise InvalidConfiguration, "mount guest path must be a non-empty String, got #{guest.inspect}"
+        end
+        unless guest.start_with?("/")
+          raise InvalidConfiguration, "mount guest path must be absolute, got #{guest.inspect}"
+        end
+
+        guest = guest.chomp("/")
+        if guest.empty? || File.expand_path(guest, "/") != guest
+          raise InvalidConfiguration,
+                "mount guest path must be a normalized absolute path (no '..', '.' or trailing '/'), got #{guest.inspect}"
+        end
+        raise InvalidConfiguration, "mount guest path contains a NUL byte" if guest.include?("\0")
+
+        guest.freeze
+      end
+
+      def check_duplicates(mounts)
+        guests = mounts.map { |mount| mount[:guest] }
+        duplicate = guests.find { |guest| guests.count(guest) > 1 }
+        return unless duplicate
+
+        raise InvalidConfiguration, "duplicate guest mount path #{duplicate.inspect}"
+      end
+
+      def check_reserved(mounts)
+        mounts.each do |mount|
+          guest = mount[:guest]
+          conflict = RESERVED_GUEST_PATHS.find do |reserved|
+            guest == reserved || guest.start_with?("#{reserved}/") || reserved.start_with?("#{guest}/")
+          end
+          next unless conflict
+
+          raise InvalidConfiguration,
+                "mount guest path #{guest.inspect} overlaps the reserved path #{conflict.inspect}"
+        end
+      end
+
+      def check_count(mounts)
+        return if mounts.size <= MAX_MOUNTS
+
+        raise InvalidConfiguration,
+              "too many mounts (#{mounts.size}); the limit is #{MAX_MOUNTS}"
+      end
+    end
+  end
 end