kobako 0.27.0 → 0.29.0

data/lib/kobako/sandbox.rb

@@ -10,205 +10,196 @@ require_relative "catalog"
 require_relative "context"
 
 module Kobako
-  # Kobako::Sandbox — the user-facing entry point for executing guest mruby
-  # scripts inside a wasmtime-hosted Wasm module.
-  #
-  # The Sandbox owns the reusable configuration — the +Kobako::Runtime+ and
-  # the +Kobako::Catalog::Services+ / +Catalog::Snippets+ / +Catalog::Extensions+
-  # registries. Each +#eval+ / +#run+ seals that config on the first call and
-  # drives one guest invocation through a fresh +Kobako::Context+ — its own
-  # Handle table, dispatch +Proc+, captures, and usage — so the reusable
-  # Sandbox holds no per-invocation state. The underlying wasmtime Engine and
-  # compiled Module are cached at process scope by the native ext and never
-  # surface to Ruby — constructing many Sandboxes amortises both costs
-  # automatically.
-  #
-  # A run's observables — the captured +#stdout+ / +#stderr+ (bounded by
-  # +stdout_limit+ / +stderr_limit+, enforced inside the WASI pipe) with their
-  # +#stdout_truncated?+ / +#stderr_truncated?+ predicates, and +#usage+ — live
-  # on the +Kobako::Execution+ each +#eval+ / +#run+ returns, or on the one its
-  # raised error carries. The Sandbox itself keeps none of them, so nothing a
-  # run observes carries into the next one.
+  # Runs untrusted mruby scripts in an isolated Wasm instance. Configure it
+  # once, binding Services and preloading snippets, then call #eval or #run as
+  # often as needed: each call returns an Execution and leaves nothing behind
+  # for the next.
   class Sandbox
     extend Forwardable
 
-    attr_reader :wasm_path, :options
+    # The Guest Binary this Sandbox runs.
+    attr_reader :wasm_path
 
-    # Per-option accessors forward to the immutable +SandboxOptions+ Value
-    # Object so the Host App still reads them off Sandbox directly.
-    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl
+    # The SandboxOptions this Sandbox was built with. Each option is also
+    # readable on the Sandbox itself, as in #timeout.
+    attr_reader :options
 
-    # Build a fresh Sandbox.
+    def_delegators :@options, :timeout, :setup_timeout, :memory_limit, :stdout_limit, :stderr_limit,
+                   :open_file_limit, :profile, :gvl
+
+    # Build a Sandbox on the Guest Binary at +wasm_path+, the one bundled
+    # with the gem by default. The other keywords are the options
+    # SandboxOptions describes.
     #
-    # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
-    # gem-bundled +data/kobako.wasm+. Every other keyword — the four caps
-    # (+stdout_limit+, +stderr_limit+, +timeout+, +memory_limit+) and the
-    # requested isolation profile (+profile+) — is forwarded verbatim to
-    # +Kobako::SandboxOptions+, which owns the DEFAULT fallbacks and
-    # normalisation. The constructed +SandboxOptions+ is exposed as
-    # +#options+ and every option remains readable directly on Sandbox via
-    # +Forwardable+ delegation. The runtime builds the requested profile —
-    # +:hermetic+ (the default) denies the guest ambient time and entropy,
-    # +:permissive+ leaves them live — and construction refuses a runtime
-    # whose declared profile falls below the request, raising
-    # +Kobako::SetupError+ before any invocation entry point runs.
+    # Raises ArgumentError for an invalid option, and SetupError when the
+    # runtime cannot be built or provides less isolation than +profile+ asks
+    # for.
     def initialize(wasm_path: nil, **)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(**)
       @services = Kobako::Catalog::Services.new
       @snippets = Catalog::Snippets.new
+      @flags = Catalog::Flags.new
       @extensions = Catalog::Extensions.new
+      @grants = Catalog::Grants.new
+      @sealed = false
       @runtime = build_runtime!
     end
 
-    # Bind +object+ as the Service reachable at +path+ — a Symbol or
-    # String of one or more +::+-separated constant-form segments
-    # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
-    # chaining.
+    # Make +object+ reachable from the guest as the constant at +path+, a
+    # Symbol or String such as <tt>"MyService::KV"</tt>. Returns +self+.
     #
-    # The guest reaches the public methods +object+'s own class and +object+
-    # itself define in source, fixed at this call — nothing inherited, mixed
-    # in, or built into the platform. An +object+ defining a private
-    # +respond_to_guest?(name)+ decides instead, asked on every call.
+    # The guest reaches the public methods that +object+'s own class and
+    # +object+ itself define in source, nothing inherited or mixed in. An
+    # +object+ defining a private <tt>respond_to_guest?(name)</tt> decides
+    # instead, on every call.
     #
-    # Called with only a +path+, it declares a fillable Service:
-    # +bind(path)+ reserves the path for +Kobako::Unresolved+, so the guest
-    # sees the constant while the host defers the object it stands for. A
-    # guest dispatch to an unfilled fillable surfaces as
-    # +Kobako::ServiceError+ when left unrescued.
+    # Called with only +path+, it declares a fillable Service: the guest sees
+    # the constant, and Context#bind supplies the object for each invocation.
+    # A call to one left unfilled fails as a ServiceError.
     #
-    # Raises +ArgumentError+ when a segment is malformed, when +path+
-    # collides with an existing binding (a name is a bound Service or a
-    # grouping prefix, never both), or when called after the first
-    # invocation has sealed Service registration.
+    # Raises ArgumentError for a malformed path, a path under the reserved
+    # +Kobako+ namespace, a path that collides with an existing binding, or a
+    # call after the first invocation.
     def bind(path, object = Unresolved)
+      refuse_once_invoked!("bind")
       @services.bind(path, object)
       self
     end
 
-    # Install one or more Extensions — each a guest idiom (+source+) paired
-    # with an optional host +backend+, composed onto the Sandbox through
-    # +#preload+ and +#bind+. An Extension is any object exposing
-    # +name+ / +source+ / +backend+ / +depends_on+; +Kobako::Extension+ is
-    # the bundled value type. Returns +self+.
+    # Install Extensions, each guest source paired with an optional host
+    # backend. Any object answering +name+, +source+, +backend+ and
+    # +depends_on+ works; Extension is the bundled one. Returns +self+.
     #
-    # Raises +ArgumentError+ for a malformed Extension, a call after the
-    # first invocation seals registration, or — at that first invocation —
-    # an unmet +depends_on+.
+    # Raises ArgumentError for a malformed Extension, a call after the first
+    # invocation, or, at the first invocation, a missing dependency.
     def install(*extensions)
-      raise ArgumentError, "cannot install after first Sandbox invocation" if @services.sealed?
+      refuse_once_invoked!("install")
 
       extensions.each { |extension| @extensions.install(extension, snippets: @snippets, services: @services) }
       self
     end
 
-    # Register a snippet on this Sandbox in one of two forms:
+    # Mount +filesystem+, a Kobako::Filesystem, at the absolute guest path
+    # +at+, where the guest's +File+ reaches it. +access+ is +:read+ or
+    # +:read_write+; a write beneath a read-only mount fails as
+    # <tt>Errno::EROFS</tt> in the guest. Returns +self+.
     #
-    #   * +preload(code: source, name: Name)+ — +source+ is mruby source
-    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. Compile
-    #     failures surface as +Kobako::SandboxError+ on the first
-    #     invocation's replay. The +name+
-    #     becomes the snippet's +(snippet:Name)+ backtrace filename and
-    #     is the dedupe key that rejects a duplicate +code:+ snippet.
-    #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
-    #     bytecode as a +String+. The canonical name, when present,
-    #     lives in the bytecode's embedded +debug_info+ and is resolved
-    #     by the guest at load time; the host treats the bytes as
-    #     opaque. Structural failures surface as +Kobako::BytecodeError+
-    #     on the first invocation.
+    # A given block decides, in +access+'s place, each open and each change
+    # that reaches the mount, asked at most once for each with the guest path
+    # and +:read+ or +:read_write+. A falsy answer,
+    # or a StandardError, fails that call as <tt>Errno::EACCES</tt> in the
+    # guest and leaves the script running.
     #
-    # Subsequent invocations (+#eval+ or +#run+) replay every registered
-    # snippet — in insertion order — against the fresh +mrb_state+
-    # before per-invocation source or entrypoint resolution.
+    # Raises TypeError for a path that is no String or something other than
+    # a Filesystem, and ArgumentError for a malformed, duplicate, or nested
+    # path, an unknown access, or a call after the first invocation.
+    def mount(at, filesystem, access: :read, &policy)
+      refuse_once_invoked!("mount")
+      Runtime.validate_mount!(at, access, filesystem)
+      @grants.register(Catalog::Mount.new(at: at, access: access, filesystem: filesystem, policy: policy))
+      self
+    end
+
+    # Register a snippet that every invocation runs, in the order registered,
+    # before its own code. Returns +self+.
     #
-    # Returns +self+ to allow chaining.
+    # [<tt>preload(code: source, name: Name)</tt>]
+    #   mruby source, named <tt>(snippet:Name)</tt> in backtraces.
+    # [<tt>preload(binary: bytes)</tt>]
+    #   Precompiled RITE bytecode, trusted as host code: the unmodified
+    #   compiler output of the mruby release the Guest Binary is built on.
     #
-    # Raises +ArgumentError+ when neither form's keyword set is
-    # supplied, when both forms are mixed (e.g., +code:+ and +binary:+
-    # together, or +binary:+ paired with +name:+), when +code+ / +bytes+
-    # is not a +String+, when +name+ does not match the constant
-    # pattern, when +name+ duplicates an already-registered +code:+ form
-    # snippet, or when called after the first invocation has sealed the
-    # snippet table.
+    # Raises ArgumentError for a malformed or duplicate snippet, or a call
+    # after the first invocation. A snippet that fails to load fails every
+    # invocation with SandboxError, or BytecodeError for bytecode.
     def preload(code: nil, name: nil, binary: nil)
-      raise ArgumentError, "cannot preload after first Sandbox invocation" if @services.sealed?
+      refuse_once_invoked!("preload")
 
       @snippets.register(code: code, name: name, binary: binary)
       self
     end
 
-    # Dispatch into a preloaded entrypoint constant. Delegates host
-    # pre-flight and argument encoding to +Kobako::Transport::Run+ /
-    # +Kobako::Transport::Run#payload+: a non-Symbol/String +target+ raises
-    # +TypeError+, while a +target+ failing the constant pattern, a forged
-    # +Kobako::Handle+ in +args+ / +kwargs+, or a non-Symbol +kwargs+ key
-    # raise +ArgumentError+. The guest resolves +target+ as a top-level
-    # constant, calls +#call+ on it with +args+ / +kwargs+, and returns the
-    # deserialized result. The first invocation seals the Service registry
-    # and snippet table. Runtime errors follow the same three-class
-    # taxonomy as +#eval+.
+    # Set the flag +name+, a Symbol or String, to +value+ for every
+    # invocation; an empty +value+ is a plain switch. A Guest Binary that
+    # does not recognise the flag fails each invocation with
+    # UnsupportedFlagError, unless +advisory+ says the guest may skip it.
+    # Mark a flag advisory only when a script cannot tell it was skipped.
+    # Returns +self+.
+    #
+    # Raises ArgumentError for a malformed or duplicate flag, or a call after
+    # the first invocation.
+    def flag(name, value = "", advisory: false)
+      refuse_once_invoked!("flag")
+
+      @flags.register(name, value, advisory: advisory)
+      self
+    end
+
+    # Call +call+ on the preloaded top-level constant +target+ with +args+
+    # and +kwargs+, and return the Execution. A given block receives the
+    # invocation's Context before the guest runs.
+    #
+    # Raises TypeError when +target+ is not a Symbol or String, and
+    # ArgumentError when it is not a constant name or the arguments carry a
+    # Handle or a non-Symbol keyword. A failed run raises as #eval does.
     def run(target, *args, **kwargs, &block)
       request = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
-      new_invocation.run(request, &block)
+      Codec.within_value_budget(@options.value_budget) { new_invocation.run(request, &block) }
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+. +code+ is
-    # the mruby source as a UTF-8 String. Returns the deserialized last
-    # expression of the source.
-    #
-    # Source delivery uses the WASI stdin three-frame protocol
-    # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
-    # Frame 1 carries the preamble (Service registry snapshot), Frame 2 the
-    # user source UTF-8 bytes, and Frame 3 the snippet table registered via
-    # +#preload+. Each frame is prefixed by a 4-byte big-endian u32 length;
-    # Frame 1 and Frame 3 are mandatory-presence — an empty registry sends a
-    # present, empty frame rather than an absent one.
-    #
-    # The first invocation seals the Service registry and snippet table;
-    # subsequent +#bind+ / +#preload+ calls raise +ArgumentError+.
+    # Evaluate +code+, mruby source as a String, and return the Execution,
+    # whose +value+ is the last expression. A given block receives the
+    # invocation's Context before the guest runs.
     #
-    # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
-    # +Kobako::SandboxError+ when the guest ran to completion but failed
-    # (including when +code+ is +nil+ or not a String, or when a preloaded
-    # snippet's replay raises); +Kobako::ServiceError+ on an unrescued
-    # Service capability failure.
+    # Raises TrapError when the engine stopped the guest, a deadline or
+    # memory budget included; SandboxError when the guest failed, +code+ not
+    # being a String or the Guest Binary not starting the run included; and
+    # ServiceError when a Service call failed and the guest left it
+    # unrescued.
     def eval(code, &block)
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
-      new_invocation.eval(code, &block)
+      Codec.within_value_budget(@options.value_budget) { new_invocation.eval(code, &block) }
     end
 
     private
 
-    # Construct the +Runtime+ with the requested isolation profile and
-    # refuse one whose declared posture falls below the request —
-    # +SandboxOptions#enforce_floor!+ owns the ladder comparison, so a
-    # runtime that cannot honor the request never runs guest code.
+    # A runtime whose declared posture falls below the request never runs
+    # guest code.
     def build_runtime!
-      runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                          @options.stdout_limit, @options.stderr_limit, @options.profile,
-                                          @options.gvl)
+      runtime = Kobako::Runtime.from_path(@wasm_path, **@options.to_h)
       @options.enforce_floor!(runtime.profile)
       runtime
     end
 
-    # Seal the config on the first invocation and return a fresh
-    # per-invocation +Context+ for the verb to drive. The Context owns this
-    # run's Handle table, resolved Extension backends, captures, and usage, so
-    # no per-invocation state is written back onto the shared config.
+    # Per-invocation state lives on the Context, so nothing an invocation
+    # does is written back onto the shared config.
     def new_invocation
       begin_invocation!
-      Context.new(runtime: @runtime, services: @services, snippets: @snippets, extensions: @extensions)
+      Context.new(runtime: @runtime, services: @services, extensions: @extensions, grants: @grants,
+                  preamble: preamble(@snippets.entries))
+    end
+
+    # The one place the Preamble's parts are put together, for a compile
+    # and for every invocation alike.
+    def preamble(snippets)
+      [@services.paths, snippets, @flags.entries]
+    end
+
+    # Registration closes at the first invocation, so every invocation ships
+    # the same Services, snippets, flags, Extensions and mounts.
+    def refuse_once_invoked!(verb)
+      raise ArgumentError, "cannot #{verb} after first Sandbox invocation" if @sealed
     end
 
-    # Per-invocation prologue on the config tier: seals the Service and
-    # Extension registries on the first call (idempotent — asserting Extension
-    # dependencies then). The Service seal is the one +#bind+ / +#preload+ /
-    # +#install+ all gate on. Per-invocation provider resolution and observable
-    # state live on the +Context+, not here.
+    # Sealing before the dependency check keeps a Sandbox whose check failed
+    # closed to further registration. The sealed snippets are compiled once,
+    # before the first invocation replays them.
     def begin_invocation!
-      @services.seal!
-      @extensions.seal!
+      @sealed = true
+      @extensions.assert_dependencies!
+      @snippets.compile { |entries| @runtime.compile(preamble(entries)) }
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -3,77 +3,89 @@
 require_relative "errors"
 
 module Kobako
-  # Kobako::SandboxOptions — immutable Value Object holding the four
-  # per-Sandbox configuration caps and the requested isolation profile.
-  # Built on the +class X < Data.define(...)+ subclass form (the
-  # Steep-friendly shape — see +.rubocop.yml+ for the rationale).
+  # The options a Sandbox was built with, read through Sandbox#options or
+  # directly on the Sandbox, as in Sandbox#timeout. A cap left out takes its
+  # default, and +nil+ switches it off.
   #
-  # The +initialize+ normalises every option before delegating to Data's
-  # +super+: +timeout+ to Float seconds, +memory_limit+ / +stdout_limit+ /
-  # +stderr_limit+ to positive Integer bytes. Each cap is +nil+-disablable
-  # (an absent argument takes its DEFAULT; an explicit +nil+ leaves the
-  # bound off), so all four behave uniformly. +profile+ is the one
-  # non-cap: a Symbol on the PROFILES ladder naming the posture the
-  # runtime builds, which is also the weakest the Host App accepts —
-  # +nil+ is rejected because the weakest posture is requested as an
-  # explicit +:permissive+. Anything that survives +SandboxOptions.new+
-  # is a wire-ready bundle the +Kobako::Runtime+ constructor consumes
-  # as-is. The options also own the ladder comparison
-  # (+#enforce_floor!+) that +Kobako::Sandbox+ delegates its
-  # construction floor check to.
-  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl)
-    # Default wall-clock timeout for a single invocation: 60 seconds.
+  # [+timeout+]       Float seconds one invocation may run.
+  # [+setup_timeout+] Float seconds the Guest Binary may take to be set up
+  #                   the first time its path is loaded.
+  # [+memory_limit+]  Integer bytes one invocation may grow guest memory by.
+  # [+stdout_limit+, +stderr_limit+]
+  #                   Integer bytes kept from each output channel.
+  # [+open_file_limit+]
+  #                   Integer descriptors one invocation may hold open, the
+  #                   standard ones and each Mount's included.
+  # [+profile+]       The isolation the runtime must provide, one of PROFILES.
+  # [+gvl+]           How an invocation holds Ruby's GVL, one of GVL_MODES.
+  #
+  # Raises ArgumentError for a value outside these shapes, and SetupError
+  # when the runtime provides less isolation than +profile+ asks for.
+  class SandboxOptions < Data.define(:timeout, :setup_timeout, :memory_limit, :stdout_limit, :stderr_limit,
+                                     :open_file_limit, :profile, :gvl)
+    # The default +timeout+: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
-    # Default cap on the per-invocation guest linear-memory delta:
-    # 1 MiB. The mruby image's initial allocation and prior invocations'
-    # watermark sit outside this budget.
-    DEFAULT_MEMORY_LIMIT = 1 << 20
+    # The default +setup_timeout+: 10 seconds.
+    DEFAULT_SETUP_TIMEOUT_SECONDS = 10.0
+
+    # The default +memory_limit+: 4 MiB of growth past the guest's starting
+    # memory, sized for a guest whose every value takes 16 bytes.
+    DEFAULT_MEMORY_LIMIT = 4 << 20
 
-    # Default per-channel capture ceiling: 1 MiB.
+    # The default +stdout_limit+ and +stderr_limit+: 1 MiB each.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
-    # The isolation ladder, weakest first — index order is rank order,
-    # so a floor check is an index comparison.
+    # The default +open_file_limit+: 1024, the soft limit Linux gives a
+    # process.
+    DEFAULT_OPEN_FILE_LIMIT = 1024
+
+    # The isolation profiles, weakest first. +:hermetic+ denies the guest the
+    # clock and entropy; +:permissive+ leaves them live.
     PROFILES = %i[permissive hermetic].freeze
 
-    # Default isolation profile: the strictest rung — opting down to
-    # +:permissive+ is the Host App's explicit trade.
+    # The default +profile+, the strictest.
     DEFAULT_PROFILE = :hermetic
 
-    # The GVL scheduling modes: +:hold+ keeps Ruby's GVL for the whole
-    # invocation, +:release+ drops it for the guest span so distinct
-    # Sandboxes on distinct Threads run their guest code in parallel.
+    # +:hold+ keeps the GVL through the invocation; +:release+ drops it while
+    # the guest runs, so Sandboxes on different Threads run in parallel.
     GVL_MODES = %i[hold release].freeze
 
-    # Default GVL mode: +:hold+ — holding the GVL matches single-threaded
-    # execution, so +:release+ is the Host App's explicit opt-in for
-    # host-parallel guest execution.
+    # The default +gvl+, +:hold+.
     DEFAULT_GVL = :hold
 
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
+                   setup_timeout: DEFAULT_SETUP_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: DEFAULT_OUTPUT_LIMIT,
                    stderr_limit: DEFAULT_OUTPUT_LIMIT,
+                   open_file_limit: DEFAULT_OPEN_FILE_LIMIT,
                    profile: DEFAULT_PROFILE,
                    gvl: DEFAULT_GVL)
-      timeout = normalize_timeout(timeout)
-      memory_limit = normalize_memory_limit(memory_limit)
-      stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
-      stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
-      profile = normalize_profile(profile)
-      gvl = normalize_gvl(gvl)
+      timeout = normalize_timeout(timeout, "timeout")
+      setup_timeout = normalize_timeout(setup_timeout, "setup_timeout")
+      memory_limit = normalize_limit(memory_limit, "memory_limit")
+      stdout_limit = normalize_limit(stdout_limit, "stdout_limit")
+      stderr_limit = normalize_limit(stderr_limit, "stderr_limit")
+      open_file_limit = normalize_limit(open_file_limit, "open_file_limit")
+      profile = normalize_choice(profile, PROFILES, "profile")
+      gvl = normalize_choice(gvl, GVL_MODES, "gvl")
       super
     end
 
-    # Enforce the requested +profile+ as the floor against +declared+ —
-    # the posture a runtime reports having built — so a runtime that
-    # cannot honor the request fails construction with
-    # +Kobako::SetupError+ instead of weakening the posture silently.
-    # Both fallbacks fail closed: a declaration off the PROFILES ladder
-    # ranks below every request, and a request off the ladder
-    # (unreachable past +initialize+) refuses every declaration.
-    def enforce_floor!(declared)
+    # The least guest memory one value occupies, so a guest payload may hold
+    # one value for each of these bytes of +memory_limit+
+    # (docs/wire/payload-msgpack.md § Value Budget).
+    VALUE_BYTES = 16
+    private_constant :VALUE_BYTES
+
+    def value_budget # :nodoc:
+      memory_limit&./(VALUE_BYTES)
+    end
+
+    # Both fallbacks fail closed: an unknown declaration ranks below every
+    # request, and an unknown request refuses every declaration.
+    def enforce_floor!(declared) # :nodoc:
       return if (PROFILES.index(declared) || -1) >= (PROFILES.index(profile) || PROFILES.size)
 
       raise Kobako::SetupError, "runtime declares isolation profile #{declared.inspect}, " \
@@ -82,39 +94,19 @@ module Kobako
 
     private
 
-    # Coerce +timeout+ into the Float seconds the ext expects, or +nil+
-    # to mean the cap is disabled. Any finite non-positive value is
-    # rejected — a zero or negative timeout would either fire instantly
-    # or never, both of which would surprise callers more than an early
-    # +ArgumentError+.
-    def normalize_timeout(timeout)
+    # A zero or negative timeout would either fire instantly or never, both
+    # more surprising than an early ArgumentError.
+    def normalize_timeout(timeout, name)
       return nil if timeout.nil?
-      raise ArgumentError, "timeout must be Numeric or nil, got #{timeout.class}" unless timeout.is_a?(Numeric)
+      raise ArgumentError, "#{name} must be Numeric or nil, got #{timeout.class}" unless timeout.is_a?(Numeric)
 
       seconds = timeout.to_f
-      raise ArgumentError, "timeout must be > 0 (got #{timeout})" unless seconds.positive? && seconds.finite?
+      raise ArgumentError, "#{name} must be > 0 (got #{timeout})" unless seconds.positive? && seconds.finite?
 
       seconds
     end
 
-    # Coerce +memory_limit+ into the byte cap the ext expects, or +nil+
-    # to mean unbounded. Must be a positive Integer when set; Float or
-    # zero/negative values are rejected.
-    def normalize_memory_limit(memory_limit)
-      return nil if memory_limit.nil?
-      unless memory_limit.is_a?(Integer) && memory_limit.positive?
-        raise ArgumentError, "memory_limit must be a positive Integer or nil, got #{memory_limit.inspect}"
-      end
-
-      memory_limit
-    end
-
-    # Coerce a per-channel output cap (+stdout_limit+ / +stderr_limit+)
-    # into the byte cap the ext expects, or +nil+ to leave the channel
-    # uncapped. Same shape as +normalize_memory_limit+: a positive Integer
-    # when set, Float / zero / negative rejected. +name+ tags the
-    # +ArgumentError+ with the offending keyword.
-    def normalize_output_limit(limit, name)
+    def normalize_limit(limit, name)
       return nil if limit.nil?
       unless limit.is_a?(Integer) && limit.positive?
         raise ArgumentError, "#{name} must be a positive Integer or nil, got #{limit.inspect}"
@@ -123,23 +115,12 @@ module Kobako
       limit
     end
 
-    # Validate +profile+ against the PROFILES ladder. Unlike the caps
-    # there is no +nil+ form: the weakest posture is requested as an
-    # explicit +:permissive+, so anything off the ladder — +nil+
-    # included — is rejected.
-    def normalize_profile(profile)
-      return profile if PROFILES.include?(profile)
-
-      raise ArgumentError, "profile must be one of #{PROFILES.map(&:inspect).join(", ")}, got #{profile.inspect}"
-    end
-
-    # Validate +gvl+ against GVL_MODES. Like +profile+ it has no +nil+
-    # form: the scheduling mode is requested as an explicit Symbol, so
-    # anything off the set — +nil+ included — is rejected.
-    def normalize_gvl(gvl)
-      return gvl if GVL_MODES.include?(gvl)
+    # Unlike the caps there is no +nil+ form: every choice, the weakest
+    # included, is requested by name, as in +:permissive+.
+    def normalize_choice(value, choices, name)
+      return value if choices.include?(value)
 
-      raise ArgumentError, "gvl must be one of #{GVL_MODES.map(&:inspect).join(", ")}, got #{gvl.inspect}"
+      raise ArgumentError, "#{name} must be one of #{choices.map(&:inspect).join(", ")}, got #{value.inspect}"
     end
   end
 end

data/lib/kobako/snippet/bytecode.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Snippet
+    class Bytecode < Data.define(:body) # :nodoc:
+      # Names the snippet form the guest replays this entry as. The wire's
+      # discriminant byte is assigned by the core envelope, not here.
+      KIND = :bytecode
+    end
+  end
+end

data/lib/kobako/snippet/source.rb

@@ -2,22 +2,7 @@
 
 module Kobako
   module Snippet
-    # Kobako::Snippet::Source — value object representing a single
-    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+.
-    #
-    # +name+ is the canonical +Symbol+ identity baked into the loaded
-    # IREP's +debug_info+; backtrace frames originating in this snippet
-    # surface as +(snippet:Name):line+. +body+ is the UTF-8 mruby source
-    # detached from the caller's reference at +Catalog::Snippets#register+
-    # time so later mutation of the original String cannot bleed through.
-    #
-    # The class is a +Data.define+ subclass — frozen, value-equal, and
-    # carries no mutation API. Callers (chiefly +Catalog::Snippets+)
-    # construct instances via keyword form +Source.new(name: ..., body: ...)+.
-    # Wire-form construction is the registry's responsibility: as a leaf
-    # carrier this Source stays pure and +Catalog::Snippets#entries+ reads
-    # its attributes off the outside rather than asking it to project itself.
-    class Source < Data.define(:name, :body)
+    class Source < Data.define(:name, :body) # :nodoc:
       # Names the snippet form the guest replays this entry as. The wire's
       # discriminant byte is assigned by the core envelope, not here.
       KIND = :source

data/lib/kobako/snippet.rb

@@ -1,17 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "snippet/binary"
+require_relative "snippet/bytecode"
 require_relative "snippet/source"
 
 module Kobako
-  # Kobako::Snippet — value-object family for preloaded snippet entries
-  # held by +Kobako::Catalog::Snippets+.
-  #
-  # +Source+ represents a single +#preload(code:, name:)+ entry; +Binary+
-  # represents a single +#preload(binary:)+ entry. Both are plain value
-  # objects with no dependency on the +Catalog::Snippets+ registry that
-  # holds them — the registry reads their attributes externally into the
-  # tuples the native side frames.
-  module Snippet
+  module Snippet # :nodoc:
   end
 end