kobako 0.28.0 → 0.30.0

data/ext/kobako/src/runtime.rs

@@ -2,11 +2,11 @@
 //!
 //! The Ruby-visible classes are
 //!
-//!   Kobako::Runtime           — wraps a `kobako_wasmtime::Driver`
-//!   Kobako::Runtime::Snapshot — one invocation's completion + captures + usage
+//!   Kobako::Runtime  — wraps a `kobako_wasmtime::Driver`
+//!   Kobako::Snapshot — one invocation's completion + captures + usage
 //!
 //! `Kobako::Runtime` is constructed via `Kobako::Runtime.from_path(path,
-//! timeout, memory_limit, stdout_limit, stderr_limit, profile)`. Every
+//! **options)`, the options keyed by the `Kobako::SandboxOptions` members. Every
 //! invocation (`#eval` / `#run`) takes that run's dispatch handler as a call
 //! argument, instantiates a fresh instance, and returns a `Snapshot` — the
 //! whole per-invocation result — so the Runtime holds no per-invocation
@@ -19,11 +19,16 @@
 
 mod bridge;
 mod errors;
+mod escape;
+mod filesystem;
 mod gvl;
+mod pinned_value;
+mod snapshot;
 
 use magnus::{
-    function, method, prelude::*, typed_data::DataTypeFunctions, value::Opaque,
-    Error as MagnusError, Exception, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
+    function, method, prelude::*, scan_args::get_kwargs, typed_data::DataTypeFunctions,
+    value::Opaque, Error as MagnusError, RArray, RHash, RModule, RString, Ruby, Symbol, TypedData,
+    Value,
 };
 
 use std::path::Path;
@@ -33,15 +38,10 @@ use std::time::Duration;
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Runtime as ContractRuntime};
-use kobako_runtime::snapshot::{Completion, Snapshot as RuntimeSnapshot};
-use kobako_transport::envelope::{Bindings, Flag, Outcome, Preamble, Snippet, Snippets};
+use kobako_transport::envelope::{Bindings, Flag, Preamble, Snippet, Snippets};
 use kobako_wasmtime::{Config, Driver};
 
-/// A Panic's fields as they cross to Ruby: origin, class, message,
-/// backtrace, and the names the invocation could have used in place of the
-/// one it named. Named so the Ruby side reads them positionally against one
-/// shape, matching the `Kobako::Outcome::panic_fields` alias.
-type PanicFields = (String, String, String, Vec<String>, Vec<String>);
+use snapshot::Snapshot;
 
 /// The one place the boundary borrows an RString's bytes: the borrow does
 /// not outlive this call, so no Ruby allocation can move the RString
@@ -53,7 +53,7 @@ fn rstring_to_vec(s: RString) -> Vec<u8> {
 
 /// `kind` arrives as a Symbol so the registry never names the wire's
 /// discriminant; an off-ladder kind raises rather than defaulting.
-fn snippets_from(ruby: &Ruby, entries: RArray) -> Result<Snippets, MagnusError> {
+fn to_snippets(ruby: &Ruby, entries: RArray) -> Result<Snippets, MagnusError> {
     let mut snippets = Snippets {
         entries: Vec::with_capacity(entries.len()),
     };
@@ -80,16 +80,16 @@ fn snippets_from(ruby: &Ruby, entries: RArray) -> Result<Snippets, MagnusError>
 }
 
 /// One owner for the Preamble every guest entry reads, so an invocation
-/// and a compile cannot drift in what they send.
-fn preamble_from(
-    ruby: &Ruby,
-    paths: Vec<String>,
-    snippets: RArray,
-    flags: RArray,
-) -> Result<Preamble, MagnusError> {
+/// and a compile cannot drift in what they send. An invocation's setup
+/// and a compile's preamble both open with its paths, snippets, and flags.
+fn to_preamble(ruby: &Ruby, parts: RArray) -> Result<Preamble, MagnusError> {
+    let paths: RArray = parts.entry(0)?;
+    let flags: RArray = parts.entry(2)?;
     let mut preamble = Preamble::default();
-    preamble.bindings = Bindings { paths };
-    preamble.snippets = snippets_from(ruby, snippets)?;
+    preamble.bindings = Bindings {
+        paths: paths.to_vec()?,
+    };
+    preamble.snippets = to_snippets(ruby, parts.entry(1)?)?;
     preamble.flags = flags
         .to_vec::<(String, String, bool)>()?
         .into_iter()
@@ -111,27 +111,32 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // directly into those classes through the constructors and mappers
     // in `runtime/errors.rs` — no intermediate hierarchy is registered.
 
+    // This extension is the only frontend in its process, so the first
+    // registration is the one that stands.
+    let _ = kobako_runtime::sched::register_blocking(Box::new(gvl::GvlFreeWait));
+
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
-    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 7))?;
-    runtime.define_method("eval", method!(Runtime::eval, 5))?;
-    runtime.define_method("run", method!(Runtime::run, 6))?;
+    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 2))?;
+    runtime.define_method("eval", method!(Runtime::eval, 3))?;
+    runtime.define_method("run", method!(Runtime::run, 4))?;
     runtime.define_method("profile", method!(Runtime::profile, 0))?;
-    runtime.define_method("compile", method!(Runtime::compile, 3))?;
+    runtime.define_method("compile", method!(Runtime::compile, 1))?;
+    runtime.define_singleton_method("validate_mount", function!(filesystem::validate_mount, 3))?;
     // The guest re-enters for a block yield through a frame-scoped
-    // `Kobako::Runtime::GuestYielder` the dispatcher hands the Proc, not a
-    // method on Runtime.
-    bridge::register(runtime)?;
+    // `Kobako::GuestYielder` the dispatcher hands the Proc, not a method on
+    // Runtime.
+    bridge::register(kobako)?;
+    filesystem::register(ruby, kobako)?;
 
     // Snapshot — the per-invocation result object each entry point returns.
-    let snapshot = runtime.define_class("Snapshot", ruby.class_object())?;
-    snapshot.define_method("outcome", method!(Snapshot::outcome, 0))?;
-    snapshot.define_method("trap_error", method!(Snapshot::trap_error, 0))?;
-    snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
-    snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
-    snapshot.define_method("stdout", method!(Snapshot::stdout, 0))?;
-    snapshot.define_method("stdout_truncated?", method!(Snapshot::stdout_truncated, 0))?;
-    snapshot.define_method("stderr", method!(Snapshot::stderr, 0))?;
-    snapshot.define_method("stderr_truncated?", method!(Snapshot::stderr_truncated, 0))?;
+    snapshot::register(ruby, kobako)?;
+
+    // A wrapped class is otherwise looked up the first time an object is
+    // wrapped, through a Ruby call that a pending interrupt would turn into
+    // a panic; a signal arriving during a process's first run waits for
+    // exactly that moment.
+    Runtime::class(ruby);
+    Snapshot::class(ruby);
 
     Ok(())
 }
@@ -157,34 +162,61 @@ impl DataTypeFunctions for Runtime {}
 
 impl Runtime {
     /// The only Ruby-facing constructor, so Engine and Module are never
-    /// visible to Ruby.
-    fn from_path(
-        path: String,
-        timeout_seconds: Option<f64>,
-        memory_limit: Option<usize>,
-        stdout_limit: Option<usize>,
-        stderr_limit: Option<usize>,
-        profile: Symbol,
-        gvl: Symbol,
-    ) -> Result<Self, MagnusError> {
+    /// visible to Ruby. Every option is a required keyword: the defaults
+    /// belong to `Kobako::SandboxOptions`, which names the keys.
+    fn from_path(path: String, options: RHash) -> Result<Self, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
-        let timeout = match timeout_seconds {
-            None => None,
-            Some(secs) if secs.is_finite() && secs > 0.0 => Some(Duration::from_secs_f64(secs)),
-            Some(secs) => {
-                // An invalid cap argument is a Host App
-                // programming error and raises `ArgumentError`, outside the
-                // construction-failure `SetupError` branch. `SandboxOptions`
-                // is the primary guard (it never lets a bad timeout reach
-                // here); this is defence-in-depth for direct `from_path` calls.
-                return Err(MagnusError::new(
-                    ruby.exception_arg_error(),
-                    format!("timeout must be > 0 and finite, got {secs} seconds"),
-                ));
-            }
+        type Options = (
+            Option<f64>,
+            Option<f64>,
+            Option<usize>,
+            Option<usize>,
+            Option<usize>,
+            Option<usize>,
+            Symbol,
+            Symbol,
+        );
+        let options = get_kwargs::<_, Options, (), ()>(
+            options,
+            &[
+                "timeout",
+                "setup_timeout",
+                "memory_limit",
+                "stdout_limit",
+                "stderr_limit",
+                "open_file_limit",
+                "profile",
+                "gvl",
+            ],
+            &[],
+        )?;
+        let (
+            timeout_seconds,
+            setup_timeout_seconds,
+            memory_limit,
+            stdout_limit,
+            stderr_limit,
+            open_file_limit,
+            profile,
+            gvl,
+        ) = options.required;
+        // An invalid cap argument is a Host App programming error and
+        // raises `ArgumentError`, outside the construction-failure
+        // `SetupError` branch. `SandboxOptions` is the primary guard (it
+        // never lets a bad timeout reach here); this is defence-in-depth
+        // for direct `from_path` calls.
+        let to_duration = |seconds: Option<f64>, name: &str| match seconds {
+            None => Ok(None),
+            Some(secs) if secs.is_finite() && secs > 0.0 => Ok(Some(Duration::from_secs_f64(secs))),
+            Some(secs) => Err(MagnusError::new(
+                ruby.exception_arg_error(),
+                format!("{name} must be > 0 and finite, got {secs} seconds"),
+            )),
         };
+        let timeout = to_duration(timeout_seconds, "timeout")?;
+        let setup_timeout = to_duration(setup_timeout_seconds, "setup_timeout")?;
         // Fail closed on an off-ladder rung: an unrecognized posture must
-        // never fall back to a grant. Same defence-in-depth posture as the
+        // never fall back to a weaker posture. Same defence in depth as the
         // timeout guard above — `SandboxOptions` is the primary validator.
         let profile = match profile.name()?.as_ref() {
             "hermetic" => Profile::Hermetic,
@@ -210,17 +242,16 @@ impl Runtime {
             }
         };
 
-        let driver = Driver::new(
-            Path::new(&path),
-            Config {
-                timeout,
-                memory_limit,
-                stdout_limit,
-                stderr_limit,
-                profile,
-            },
-        )
-        .map_err(|e| errors::setup_to_magnus(&ruby, e))?;
+        let mut config = Config::default();
+        config.timeout = timeout;
+        config.setup_timeout = setup_timeout;
+        config.memory_limit = memory_limit;
+        config.stdout_limit = stdout_limit;
+        config.stderr_limit = stderr_limit;
+        config.open_file_limit = open_file_limit;
+        config.profile = profile;
+        let driver =
+            Driver::new(Path::new(&path), config).map_err(|e| errors::setup_to_magnus(&ruby, e))?;
         Ok(Self {
             driver,
             release_gvl,
@@ -233,40 +264,32 @@ impl Runtime {
     // success or trap alike. Only a could-not-start fault (a missing export
     // or a fault before the export call) raises directly, as the class
     // `errors::to_magnus` gives its cause, since it yields no `Snapshot`.
+    //
+    // `setup` is the invocation's `[paths, snippets, flags, mounts]`: the
+    // Preamble's three parts, then the Mounts as
+    // `filesystem::to_grants` reads them.
     // -----------------------------------------------------------------
 
     fn eval(
         &self,
         dispatch: Value,
-        paths: RArray,
-        snippets: RArray,
-        flags: RArray,
+        setup: RArray,
         source: RString,
     ) -> Result<Snapshot, MagnusError> {
         let source = rstring_to_vec(source);
-        self.invoke(
-            dispatch,
-            paths,
-            snippets,
-            flags,
-            Entry::Eval { source: &source },
-        )
+        self.invoke(dispatch, setup, Entry::Eval { source: &source })
     }
 
     fn run(
         &self,
         dispatch: Value,
-        paths: RArray,
-        snippets: RArray,
-        flags: RArray,
+        setup: RArray,
         entrypoint: String,
         payload: RString,
     ) -> Result<Snapshot, MagnusError> {
         self.invoke(
             dispatch,
-            paths,
-            snippets,
-            flags,
+            setup,
             Entry::Run {
                 entrypoint: &entrypoint,
                 payload: rstring_to_vec(payload),
@@ -274,14 +297,12 @@ impl Runtime {
         )
     }
 
-    /// One owner for the wiring both verbs share, so a Preamble or handler
-    /// change cannot drift between them.
+    /// One owner for the wiring both verbs share, so a Preamble, a Grant,
+    /// or a handler change cannot drift between them.
     fn invoke(
         &self,
         dispatch: Value,
-        paths: RArray,
-        snippets: RArray,
-        flags: RArray,
+        setup: RArray,
         entry: Entry<'_>,
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
@@ -290,15 +311,17 @@ impl Runtime {
             Entry::Run { .. } => "run",
         };
         let handler = build_handler(dispatch);
-        let preamble = preamble_from(&ruby, paths.to_vec()?, snippets, flags)?;
+        let preamble = to_preamble(&ruby, setup)?;
+        let (grants, _pins) = filesystem::to_grants(&ruby, setup.entry(3)?)?;
         // Release the GVL around the guest span iff this Sandbox asks for it;
         // the closure touches no Ruby VALUE (the driver is magnus-free, and a
-        // guest→host dispatch re-acquires the GVL through the bridge).
+        // guest→host dispatch, or a mount's block, re-acquires the GVL).
         let result = gvl::region(self.release_gvl, || {
-            self.driver.invoke(entry, &preamble, handler)
+            self.driver.invoke(entry, &preamble, handler, &grants)
         });
+        escape::resume()?;
         result
-            .map(|snapshot| Snapshot(snapshot, verb))
+            .map(|snapshot| Snapshot::new(snapshot, verb))
             .map_err(|e| errors::to_magnus(&ruby, e))
     }
 
@@ -308,15 +331,11 @@ impl Runtime {
     /// invocation sends, `paths` included, so the driver can tell whether
     /// the bytecode still fits it; no dispatch handler is bound, since
     /// compiling runs no script.
-    fn compile(
-        &self,
-        paths: RArray,
-        snippets: RArray,
-        flags: RArray,
-    ) -> Result<Option<RArray>, MagnusError> {
+    fn compile(&self, preamble: RArray) -> Result<Option<RArray>, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
-        let preamble = preamble_from(&ruby, paths.to_vec()?, snippets, flags)?;
+        let preamble = to_preamble(&ruby, preamble)?;
         let bytecodes = gvl::region(self.release_gvl, || self.driver.compile(&preamble));
+        escape::resume()?;
         Ok(bytecodes.map(|bytecodes| {
             ruby.ary_from_iter(
                 bytecodes
@@ -349,96 +368,3 @@ fn build_handler(dispatch: Value) -> Option<Arc<dyn DispatchHandler>> {
             as Arc<dyn DispatchHandler>,
     )
 }
-
-/// One invocation's result at the Ruby boundary — the whole `Snapshot` the
-/// driver produced, exposed as `Kobako::Runtime::Snapshot`. Usage and the
-/// two output captures are present on every outcome, so the trap path
-/// carries them just like the value path; the completion is read as either
-/// the Outcome (`#outcome`) or a trap (`#trap_error`). The verb names the
-/// invocation, so an unsupported one says which operation is lacking.
-#[derive(TypedData)]
-#[magnus(class = "Kobako::Runtime::Snapshot", free_immediately, size)]
-struct Snapshot(RuntimeSnapshot, &'static str);
-
-impl DataTypeFunctions for Snapshot {}
-
-impl Snapshot {
-    /// Already split off the core envelope, so the Ruby side maps a failure
-    /// onto its error taxonomy without decoding a payload byte: the ok
-    /// arm's payload, or a Panic's fields beside an empty payload. A trap
-    /// has no Outcome; `#trap_error` is the discriminator there.
-    fn outcome(&self) -> Result<(RString, Option<PanicFields>), MagnusError> {
-        let ruby = Ruby::get().expect("Ruby thread");
-        match &self.0.completion {
-            Completion::Outcome(Outcome::Ok(value)) => Ok((ruby.str_from_slice(value), None)),
-            Completion::Outcome(Outcome::Panic(panic)) => Ok((
-                ruby.str_from_slice(&[]),
-                Some((
-                    panic.origin.name().to_owned(),
-                    panic.error.name.clone(),
-                    panic.error.message.clone(),
-                    panic.error.backtrace.clone(),
-                    panic.available.clone(),
-                )),
-            )),
-            // The Guest Binary answered rather than broke, so it reads as
-            // the Sandbox's failure, worded by the host.
-            Completion::Outcome(Outcome::Unsupported(_)) => Ok((
-                ruby.str_from_slice(&[]),
-                Some((
-                    "sandbox".to_owned(),
-                    "Kobako::SandboxError".to_owned(),
-                    format!(
-                        "the Sandbox runtime does not support #{}; \
-                         rebuild it against the kobako version in use",
-                        self.1
-                    ),
-                    Vec::new(),
-                    Vec::new(),
-                )),
-            )),
-            Completion::Trap(_) => Err(MagnusError::new(
-                ruby.exception_runtime_error(),
-                "a trapped run has no outcome",
-            )),
-        }
-    }
-
-    /// Unraised, so the Sandbox layer can attach the run's Execution before
-    /// raising it.
-    fn trap_error(&self) -> Result<Option<Exception>, MagnusError> {
-        let Completion::Trap(trap) = &self.0.completion else {
-            return Ok(None);
-        };
-        let ruby = Ruby::get().expect("Ruby thread");
-        errors::trap_class(&ruby, trap)
-            .new_instance((trap.to_string(),))
-            .map(Some)
-    }
-
-    fn wall_time(&self) -> f64 {
-        self.0.usage.wall_time
-    }
-
-    fn memory_peak(&self) -> usize {
-        self.0.usage.memory_peak
-    }
-
-    fn stdout(&self) -> RString {
-        let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.0.stdout.bytes)
-    }
-
-    fn stdout_truncated(&self) -> bool {
-        self.0.stdout.truncated
-    }
-
-    fn stderr(&self) -> RString {
-        let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.0.stderr.bytes)
-    }
-
-    fn stderr_truncated(&self) -> bool {
-        self.0.stderr.truncated
-    }
-}

data/lib/kobako/catalog/extensions.rb

@@ -16,10 +16,10 @@ module Kobako
       # The Extension readers are duck-typed, so a malformed +name+ or
       # +backend.path+ surfaces through the registry it routes to.
       def install(extension, snippets:, services:)
-        validate!(extension)
+        validate(extension)
         snippets.register(code: extension.source, name: extension.name)
         backend = extension.backend
-        services.bind(backend.path, install_object(backend)) if backend
+        services.bind(backend.path, object_of(backend)) if backend
         @entries << extension
         self
       end
@@ -27,7 +27,7 @@ module Kobako
       # The asserted flag flips only on success, so a check that failed
       # re-runs on the next invocation rather than silently passing a broken
       # Sandbox.
-      def assert_dependencies!
+      def assert_dependencies
         return self if @asserted
 
         extension, dependency = unmet_dependency
@@ -52,7 +52,7 @@ module Kobako
 
       private
 
-      def install_object(backend) = backend.object.nil? ? Kobako::Unresolved : backend.object
+      def object_of(backend) = backend.object.nil? ? Kobako::Unresolved : backend.object
 
       def resolve_backend(extension, resolved, by_provider)
         backend = extension.backend
@@ -64,7 +64,7 @@ module Kobako
         resolved[backend.path.to_s] = by_provider.fetch(provider) { by_provider[provider] = provider.call }
       end
 
-      def validate!(extension)
+      def validate(extension)
         source = extension.source
         raise ArgumentError, "Extension #source must be a String, got #{source.class}" unless source.is_a?(String)
 

data/lib/kobako/catalog/flags.rb

@@ -18,24 +18,12 @@ module Kobako
         end
         raise ArgumentError, "flag value must be a String, got #{value.class}" unless value.is_a?(String)
 
-        key = utf8!(name.to_s, "flag name")
+        key = Catalog.to_utf8(name.to_s, "flag name")
         raise ArgumentError, "flag #{key.inspect} already set" if @entries.key?(key)
 
-        @entries[key] = [utf8!(value, "flag value"), !advisory]
+        @entries[key] = [Catalog.to_utf8(value, "flag value"), !advisory]
         nil
       end
-
-      private
-
-      # The native side carries a flag only as UTF-8 text, so text read as
-      # bytes is re-tagged, and bytes that are not UTF-8 are refused here
-      # rather than failing every invocation.
-      def utf8!(text, what)
-        utf8 = text.dup.force_encoding(Encoding::UTF_8)
-        raise ArgumentError, "#{what} must be UTF-8 text" unless utf8.valid_encoding?
-
-        utf8
-      end
     end
   end
 end

data/lib/kobako/catalog/grants.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Catalog
+    class Grants # :nodoc:
+      def initialize
+        @entries = {} # : Hash[String, Mount]
+      end
+
+      # Each Grant decides what it cannot stand beside.
+      def register(grant)
+        reason = @entries.each_value.lazy.filter_map { |other| grant.conflict(other) }.first
+        raise ArgumentError, reason if reason
+
+        @entries[grant.key] = grant
+        nil
+      end
+
+      def include?(grant)
+        @entries.key?(grant.key)
+      end
+
+      # Each Grant as the native side reads it, an override standing in for
+      # the Grant it shares a key with.
+      def entries(overrides = {})
+        @entries.merge(overrides).values.map(&:to_native)
+      end
+    end
+  end
+end

data/lib/kobako/catalog/handles.rb

@@ -23,8 +23,8 @@ module Kobako
       # call made through this Handle is authorized against the reference
       # the guest was given.
       def alloc(object)
-        reject_unwrappable!(object)
-        ensure_capacity!
+        reject_unwrappable(object)
+        ensure_capacity
         id = @next_id
         @entries[id] = Kobako::Transport::Exposure.of(object, @surfaces)
         @next_id = id + 1
@@ -36,7 +36,7 @@ module Kobako
       end
 
       def exposure(id)
-        require_bound!(id)
+        require_bound(id)
         @entries[id]
       end
 
@@ -61,7 +61,7 @@ module Kobako
       # a surface the floor reads as ordinary Service behaviour. Raising here
       # keeps the rule at the single mint point, so it holds on both the
       # Service-return and the +#run+ host→guest auto-wrap paths.
-      def reject_unwrappable!(object)
+      def reject_unwrappable(object)
         case object
         when Binding, Method, UnboundMethod, Module, Delegator
           # Delegator < BasicObject exposes no static +#class+, so name the
@@ -71,7 +71,7 @@ module Kobako
         end
       end
 
-      def ensure_capacity!
+      def ensure_capacity
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
 
@@ -80,7 +80,7 @@ module Kobako
               "in a single invocation (limit #{cap})"
       end
 
-      def require_bound!(id)
+      def require_bound(id)
         return if @entries.key?(id)
 
         raise SandboxError, "unknown Handle id: #{id.inspect}"

data/lib/kobako/catalog/mount.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Catalog
+    class Mount < Data.define(:at, :access, :filesystem, :policy) # :nodoc:
+      # The path a Context replaces this Mount at.
+      def key = at
+
+      # Why +other+ cannot be mounted beside this Mount, or +nil+: a path
+      # means one Mount, as Docker refuses a duplicate mount point.
+      def conflict(other)
+        "path #{at.inspect} is already mounted" if other.at == at
+      end
+
+      # The Mount as the native side reads it.
+      def to_native = [at, access, filesystem, policy]
+    end
+  end
+end

data/lib/kobako/catalog/services.rb

@@ -7,13 +7,20 @@ require_relative "../transport/exposure"
 module Kobako
   module Catalog
     class Services # :nodoc:
+      # The Guest Binary keeps this namespace for constants it may add later.
+      RESERVED_NAMESPACE = "Kobako"
+
       def initialize
         @bindings = {} # : Hash[String, Kobako::Transport::Exposure]
       end
 
       # The binding records +object+'s Exposure as it stands now.
       def bind(path, object)
-        path_str = validate_path!(path)
+        path_str = validate_path(path)
+        if reserved?(path_str)
+          raise ArgumentError,
+                "Service path #{path_str} is in the reserved #{RESERVED_NAMESPACE} namespace"
+        end
         raise ArgumentError, "Service path #{path_str} conflicts with an existing binding" if collision?(path_str)
 
         @bindings[path_str] = Kobako::Transport::Exposure.of(object)
@@ -39,7 +46,7 @@ module Kobako
 
       private
 
-      def validate_path!(path)
+      def validate_path(path)
         path_str = path.to_s
         segments = path_str.split("::", -1)
         return path_str if !segments.empty? && segments.all? { |seg| CONSTANT_NAME.match?(seg) }
@@ -48,6 +55,10 @@ module Kobako
               "bind path must be constant-form segments joined by '::' (got #{path.inspect})"
       end
 
+      def reserved?(path)
+        path.split("::").first == RESERVED_NAMESPACE
+      end
+
       # Keeps a name from being both a bound Service and a grouping prefix.
       def collision?(path)
         @bindings.each_key.any? do |existing|