kobako 0.26.0-aarch64-linux → 0.28.0-aarch64-linux

data/SECURITY.md

@@ -3,7 +3,7 @@
 kobako runs untrusted guest code inside an in-process Wasm sandbox, so a break in
 its isolation boundary is treated as a security issue. This file is about **reporting
 such an issue**; for how the boundary is meant to work and where your
-responsibilities as a host begin, see [`docs/security-model.md`](docs/security-model.md).
+responsibilities as a host begin, see [`docs/guides/security.md`](docs/guides/security.md).
 
 ## Supported versions
 

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.18.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.17.0...kobako-runtime-v0.18.0) (2026-10-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* **transport:** the stdin layout a Guest Binary reads changed within ABI 4. kobako_transport::envelope::Frames is replaced by Preamble, which is #[non_exhaustive] and built from Default; Bindings and Snippets no longer have their own decode and encode. Guest::eval and Guest::run, MrbGuest::eval and MrbGuest::run, and Runtime::invoke take a Preamble in place of Frames. kobako_core re-exports Preamble and Flag in place of Frames.
+* **transport:** the ABI version is 4, so a Guest Binary built for ABI 3 is refused at Sandbox construction. kobako_core::export_guest! emits __kobako_downcall in place of __kobako_eval, __kobako_run, __kobako_yield_to_block and __kobako_take_outcome, and the host import is __kobako_upcall. kobako_core::abi::{take_outcome, write_outcome, write_reply, decode_run} are replaced by serve and answer, and the frames module is no longer public. Reply, YieldReply and Outcome gain an Unsupported arm and take their tags from the shared registry, and kobako_core::DispatchError and kobako::YieldError gain an Unsupported arm. A yield to a guest without block support raises Kobako::UnsupportedError at the Service's yield instead of failing the invocation as a trap.
+* **runtime:** Runtime::invoke takes &kobako_transport::envelope::Frames in place of kobako_runtime::Frames, whose byte fields are gone. Guest::eval and Guest::run (and their MrbGuest flows) receive the decoded Frames, eval also its source; kobako_core::frames::read_frame is replaced by read_eval_frames and read_frames.
+* **runtime:** kobako_runtime::snapshot::Completion::Outcome holds a decoded kobako_transport::envelope::Outcome instead of Vec<u8>; an engine decodes the result itself and reports an unframed one as
+* **runtime:** kobako_runtime::runtime::Entry::Run holds { entrypoint: &str, payload: Vec<u8> } instead of { envelope: &[u8] }; a frontend passes the fields, and an engine encodes the Run envelope itself.
+* **runtime:** kobako_runtime::yielder::Yielder::yield_to_block returns Result<YieldReply, Trap> instead of the encoded bytes; an engine implementing it decodes the reply itself.
+
+### Features
+
+* **runtime:** compile a Preamble's snippets on an instance of their own ([303432d](https://github.com/elct9620/kobako/commit/303432dd90ed62dc378391515e68e784e1b473a4)), closes [#75](https://github.com/elct9620/kobako/issues/75)
+* **transport:** carry each operation as a tag on one channel per direction ([c7d574b](https://github.com/elct9620/kobako/commit/c7d574b59a42e58632f2bdc46cc9a8e4c7ac6121)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** set an invocation up from a Preamble of tagged records ([84d4498](https://github.com/elct9620/kobako/commit/84d4498464f94d7312f26931ddd4ec43894a6654))
+
+
+### Bug Fixes
+
+* keep a compile's bytecode only when the Preamble still fits it ([765db08](https://github.com/elct9620/kobako/commit/765db08ad31c8f5163794c7e144355f3237af93b))
+
+
+### Code Refactoring
+
+* **runtime:** hand a frontend the decoded Outcome ([0da6aac](https://github.com/elct9620/kobako/commit/0da6aac0f7943d694a5a4ab9439b2d6c527ae1b0)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** hand a frontend the decoded Yield Reply ([e80ab54](https://github.com/elct9620/kobako/commit/e80ab54e36c2a80b0f746c675f85bd1238fd4331)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the ABI endpoints frame and read the Frames ([dea069a](https://github.com/elct9620/kobako/commit/dea069ac49a59c12a6f7102ed3cf2925f316cbff)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the engine frame a run's entrypoint and payload ([62f9c94](https://github.com/elct9620/kobako/commit/62f9c9407ff3ce690723625bea075fa49d2dda47)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+
+## [0.17.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.16.0...kobako-runtime-v0.17.0) (2026-09-20)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.16.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.15.0...kobako-runtime-v0.16.0) (2026-09-15)
 
 

data/crates/kobako-runtime/README.md

@@ -6,17 +6,15 @@ 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:
-
-- `runtime` — the `Runtime` trait: one guest invocation on a fresh
-  instance in, its observable `Snapshot` out
-- `snapshot` — the per-invocation observables: `Completion` (outcome
-  or trap), the two output `Capture`s, and resource `Usage`, uniform
-  across success and trap
-- `error` — the neutral failure channels: `Trap` (engine fault) and
-  `SetupError` (the invocation never started)
-- `dispatch` / `yielder` — the `DispatchHandler` and `Yielder` traits
-  a frontend supplies for guest→host dispatch and block-yield re-entry
+type, so the engine stays swappable.
+
+| Module | What it declares |
+|---|---|
+| `runtime` | the `Runtime` trait: one guest invocation on a fresh instance in, its observable `Snapshot` out |
+| `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 |
+| `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)
@@ -26,7 +24,7 @@ map the neutral types onto their own language surface.
 
 ```toml
 [dependencies]
-kobako-runtime = "0.16.0" # x-release-please-version
+kobako-runtime = "0.18.0" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-transport/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.18.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.17.0...kobako-transport-v0.18.0) (2026-10-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* **transport:** the stdin layout a Guest Binary reads changed within ABI 4. kobako_transport::envelope::Frames is replaced by Preamble, which is #[non_exhaustive] and built from Default; Bindings and Snippets no longer have their own decode and encode. Guest::eval and Guest::run, MrbGuest::eval and MrbGuest::run, and Runtime::invoke take a Preamble in place of Frames. kobako_core re-exports Preamble and Flag in place of Frames.
+* **mruby:** CodecError::Unsupported is renamed to CodecError::Unserved; a codec of one's own that refuses a position returns the new name.
+* **transport:** the ABI version is 4, so a Guest Binary built for ABI 3 is refused at Sandbox construction. kobako_core::export_guest! emits __kobako_downcall in place of __kobako_eval, __kobako_run, __kobako_yield_to_block and __kobako_take_outcome, and the host import is __kobako_upcall. kobako_core::abi::{take_outcome, write_outcome, write_reply, decode_run} are replaced by serve and answer, and the frames module is no longer public. Reply, YieldReply and Outcome gain an Unsupported arm and take their tags from the shared registry, and kobako_core::DispatchError and kobako::YieldError gain an Unsupported arm. A yield to a guest without block support raises Kobako::UnsupportedError at the Service's yield instead of failing the invocation as a trap.
+
+### Features
+
+* **transport:** carry a compile request and its answer ([f30958e](https://github.com/elct9620/kobako/commit/f30958e7d61c95667c32cfee7d9b2d2f74550a8e)), closes [#75](https://github.com/elct9620/kobako/issues/75)
+* **transport:** carry each operation as a tag on one channel per direction ([c7d574b](https://github.com/elct9620/kobako/commit/c7d574b59a42e58632f2bdc46cc9a8e4c7ac6121)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** keep an unknown request's body, and refuse tag 0x00 ([edb64df](https://github.com/elct9620/kobako/commit/edb64df8f87694d17c5b6fd71ac63329023306ec)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** name the Frames a Sandbox is set up with ([52b25aa](https://github.com/elct9620/kobako/commit/52b25aa48d321ce8ea7dc9532cfade062118c64f)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** set an invocation up from a Preamble of tagged records ([84d4498](https://github.com/elct9620/kobako/commit/84d4498464f94d7312f26931ddd4ec43894a6654))
+
+
+### Bug Fixes
+
+* **transport:** read only an unassigned tag as an unknown request ([fcb81b5](https://github.com/elct9620/kobako/commit/fcb81b5c38d001b729a10287443c5012281b76b6)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** size a counted list by what its bytes can hold ([cfcc9fb](https://github.com/elct9620/kobako/commit/cfcc9fb6e79ec0bd1e6bf3a15659220aab0f6914))
+
+
+### Code Refactoring
+
+* **mruby:** name a codec's refused position Unserved ([91979f9](https://github.com/elct9620/kobako/commit/91979f9546a3fa2d2dec8c136ed6affc521ba6fb)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+
+## [0.17.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.16.0...kobako-transport-v0.17.0) (2026-09-20)
+
+
+### Miscellaneous Chores
+
+* **kobako-transport:** Synchronize kobako crates versions
+
 ## [0.16.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.15.0...kobako-transport-v0.16.0) (2026-09-15)
 
 

data/crates/kobako-transport/README.md

@@ -5,39 +5,55 @@ an in-process Wasm sandbox for running untrusted mruby scripts.
 
 kobako is assembled from three parts chosen independently: a host, a
 payload codec, and a guest. That works only because two things are the
-same in every assembly. This crate is both of them, and nothing else:
-
-- `envelope` — the **core envelope**, the outer frame each message rides
-  in: `Call` / `Reply` / `YieldReply` for a dispatch round-trip,
-  `Outcome` / `Panic` for how an invocation ended, `Run` / `Preamble` /
-  `Snippets` for what an invocation is handed, and the `ErrorRecord` a
-  guest failure carries
-- `abi` — the values a host and a guest must already agree on to
-  exchange a byte: the version, the packed `(ptr, len)` return layout,
-  the invocation-channel frame prefix, and the message size cap
-
-The envelope reads a message's routing fields and its ok-versus-fault
-tag without decoding a payload byte; everything the resolved method
-consumes rides through as an opaque `payload` this layer never reads.
-A decoded envelope borrows the buffer it came from, so that payload
-reaches its reader as a view rather than a copy.
-
-This crate depends on no other, and every kobako tier depends on it:
-`kobako-runtime` and `kobako-wasmtime` on the host, `kobako-core` and
-`kobako-mruby` in the guest, and any third-party engine, codec, or
-guest that composes against them.
-
-The byte layout is specified in
-[`docs/wire/envelope.md`](https://github.com/elct9620/kobako/blob/main/docs/wire/envelope.md);
-the golden vectors in this crate are derived from that document.
+same in every assembly. This crate is both of them, and nothing else.
+
+| Module | What it fixes |
+|---|---|
+| `envelope` | the **core envelope**, the outer frame each message rides in |
+| `abi` | the values both sides agree on before exchanging a byte |
+
+The envelope covers the downcall's and the upcall's requests under one
+tag registry. It also covers a dispatch round-trip, how an invocation
+ended, and what an invocation is handed, and re-exports every message
+type. The ABI values are the version, the packed `(ptr, len)` return
+layout, the length prefix the Preamble rides stdin behind, and the
+message size cap.
+
+## Opaque Payload
+
+The envelope reads a message's routing fields and its answer's tag
+without decoding a payload byte. Everything the resolved method consumes
+rides through opaque. A decoded envelope borrows the buffer it came from,
+so that payload reaches its reader as a view rather than a copy.
+
+```text
+Call { method, payload }
+                  └── opaque here; read by whoever owns the schema
+```
+
+## Dependency Position
+
+This crate depends on no other, and every kobako tier depends on it —
+including any third-party engine, codec, or guest composing against them.
+
+```text
+host   kobako-runtime · kobako-wasmtime ──┐
+guest  kobako-core · kobako-mruby ────────┴──> kobako-transport
+```
+
+The golden vectors in this crate are derived from the kobako repository's
+byte-layout document, not from this code.
 
 ## Usage
 
+Depend on it directly only to build a tier of your own; a guest shell
+reaches the same types through `kobako-core`.
+
 ```toml
 [dependencies]
-kobako-transport = "0.16.0" # x-release-please-version
+kobako-transport = "0.18.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-wasmtime/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.18.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.17.0...kobako-wasmtime-v0.18.0) (2026-10-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* the kobako and kobako-wasmtime crates declare a minimum supported Rust version of 1.96.
+* **transport:** the stdin layout a Guest Binary reads changed within ABI 4. kobako_transport::envelope::Frames is replaced by Preamble, which is #[non_exhaustive] and built from Default; Bindings and Snippets no longer have their own decode and encode. Guest::eval and Guest::run, MrbGuest::eval and MrbGuest::run, and Runtime::invoke take a Preamble in place of Frames. kobako_core re-exports Preamble and Flag in place of Frames.
+* **transport:** the ABI version is 4, so a Guest Binary built for ABI 3 is refused at Sandbox construction. kobako_core::export_guest! emits __kobako_downcall in place of __kobako_eval, __kobako_run, __kobako_yield_to_block and __kobako_take_outcome, and the host import is __kobako_upcall. kobako_core::abi::{take_outcome, write_outcome, write_reply, decode_run} are replaced by serve and answer, and the frames module is no longer public. Reply, YieldReply and Outcome gain an Unsupported arm and take their tags from the shared registry, and kobako_core::DispatchError and kobako::YieldError gain an Unsupported arm. A yield to a guest without block support raises Kobako::UnsupportedError at the Service's yield instead of failing the invocation as a trap.
+* **runtime:** Runtime::invoke takes &kobako_transport::envelope::Frames in place of kobako_runtime::Frames, whose byte fields are gone. Guest::eval and Guest::run (and their MrbGuest flows) receive the decoded Frames, eval also its source; kobako_core::frames::read_frame is replaced by read_eval_frames and read_frames.
+* **runtime:** kobako_runtime::snapshot::Completion::Outcome holds a decoded kobako_transport::envelope::Outcome instead of Vec<u8>; an engine decodes the result itself and reports an unframed one as
+* **runtime:** kobako_runtime::runtime::Entry::Run holds { entrypoint: &str, payload: Vec<u8> } instead of { envelope: &[u8] }; a frontend passes the fields, and an engine encodes the Run envelope itself.
+* **runtime:** kobako_runtime::yielder::Yielder::yield_to_block returns Result<YieldReply, Trap> instead of the encoded bytes; an engine implementing it decodes the reply itself.
+* a memory budget or deadline reached during a Service answer or a yielded block now raises Kobako::MemoryLimitError or
+
+### Features
+
+* **guest:** raise Kobako::UnsupportedError when a host does not serve a call ([db003af](https://github.com/elct9620/kobako/commit/db003af75cf2d11b5f644986aa77c0408f5f59ba)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** compile a Preamble's snippets on an instance of their own ([303432d](https://github.com/elct9620/kobako/commit/303432dd90ed62dc378391515e68e784e1b473a4)), closes [#75](https://github.com/elct9620/kobako/issues/75)
+* **transport:** carry each operation as a tag on one channel per direction ([c7d574b](https://github.com/elct9620/kobako/commit/c7d574b59a42e58632f2bdc46cc9a8e4c7ac6121)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** keep an unknown request's body, and refuse tag 0x00 ([edb64df](https://github.com/elct9620/kobako/commit/edb64df8f87694d17c5b6fd71ac63329023306ec)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** set an invocation up from a Preamble of tagged records ([84d4498](https://github.com/elct9620/kobako/commit/84d4498464f94d7312f26931ddd4ec43894a6654))
+
+
+### Bug Fixes
+
+* end the invocation as the trap a host callback into the guest hits ([b8f47d3](https://github.com/elct9620/kobako/commit/b8f47d3699a19adcfd5596af93136401a286c761))
+* keep a compile's bytecode only when the Preamble still fits it ([765db08](https://github.com/elct9620/kobako/commit/765db08ad31c8f5163794c7e144355f3237af93b))
+* **wasmtime:** keep a compile answer only when it covers every source snippet ([93e9ddd](https://github.com/elct9620/kobako/commit/93e9ddd79f714446ae713a3145c59d3d2f4145dc))
+* **wasmtime:** tell every frontend how to recover, not only the gem ([cab805a](https://github.com/elct9620/kobako/commit/cab805ab62441a0ca2c78775b7a0d7ce9cc05c43))
+* **wasmtime:** word a missing or mistyped export one way ([8ab0aee](https://github.com/elct9620/kobako/commit/8ab0aeec8bda2960b6cab0502ef51860ea9093b8))
+
+
+### Code Refactoring
+
+* **runtime:** hand a frontend the decoded Outcome ([0da6aac](https://github.com/elct9620/kobako/commit/0da6aac0f7943d694a5a4ab9439b2d6c527ae1b0)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** hand a frontend the decoded Yield Reply ([e80ab54](https://github.com/elct9620/kobako/commit/e80ab54e36c2a80b0f746c675f85bd1238fd4331)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the ABI endpoints frame and read the Frames ([dea069a](https://github.com/elct9620/kobako/commit/dea069ac49a59c12a6f7102ed3cf2925f316cbff)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the engine frame a run's entrypoint and payload ([62f9c94](https://github.com/elct9620/kobako/commit/62f9c9407ff3ce690723625bea075fa49d2dda47)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+
+
+### Build System
+
+* declare the Rust 1.96 floor wasmtime 49 sets ([f49a2df](https://github.com/elct9620/kobako/commit/f49a2df88fa51d3b0eecb619cab1e98d79bb4245))
+
+## [0.17.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.16.0...kobako-wasmtime-v0.17.0) (2026-09-20)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.16.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.15.0...kobako-wasmtime-v0.16.0) (2026-09-15)
 
 

data/crates/kobako-wasmtime/README.md

@@ -6,16 +6,14 @@ The [wasmtime](https://wasmtime.dev) implementation of the
 
 `Driver` implements the contract's `Runtime` trait over wasmtime and
 owns every engine-bound mechanic, so frontends see only the neutral
-contract surface:
+contract surface.
 
-- process-wide Engine and compiled-Module caches with an on-disk AOT
-  (`.cwasm`) artifact cache keyed by Guest Binary content
-- a pre-linked `InstancePre` per guest path; every invocation runs on
-  a fresh instance and discards its Store afterwards
-- the epoch-based wall-clock timeout and the per-invocation
-  linear-memory cap
-- ambient denial: frozen WASI clocks and a constant RNG, so a guest
-  observes no real time and no real entropy
+| Mechanic | What the driver holds |
+|---|---|
+| Compilation | process-wide Engine and compiled-Module caches, with an on-disk AOT (`.cwasm`) artifact cache keyed by Guest Binary content |
+| Instantiation | a pre-linked `InstancePre` per guest path; every invocation runs on a fresh instance and discards its Store afterwards |
+| Bounds | the epoch-based wall-clock timeout and the per-invocation linear-memory cap |
+| Ambient denial | under the default hermetic profile, frozen clocks and a constant RNG |
 
 The kobako Ruby gem's native ext is the first frontend; a Rust host
 SDK consumes the same surface.
@@ -24,7 +22,7 @@ SDK consumes the same surface.
 
 ```toml
 [dependencies]
-kobako-wasmtime = "0.16.0" # x-release-please-version
+kobako-wasmtime = "0.18.0" # x-release-please-version
 ```
 
 ## License

data/lib/kobako/capture.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module Kobako
-  # What one invocation wrote to stdout or stderr, up to that channel's
-  # cap, together with whether it wrote past the cap. Frozen, so the bytes
-  # and the flag always travel together.
-  class Capture
+  class Capture # :nodoc:
     attr_reader :bytes
 
     # The bytes read as UTF-8 when they are valid UTF-8, and as binary

data/lib/kobako/catalog/extensions.rb

@@ -4,37 +4,17 @@ require_relative "../unresolved"
 
 module Kobako
   module Catalog
-    # Kobako::Catalog::Extensions — per-Sandbox registry of installed
-    # Extensions. Composes each Extension onto the sibling registries at
-    # install time (its +source+ into +Catalog::Snippets+, its +backend+
-    # path into +Catalog::Services+), asserts declared dependencies are
-    # present when the Sandbox seals, and resolves each callable-backed
-    # path to a fresh object for every invocation — returning that map to the
-    # driving +Context+ rather than mutating the shared registry, so
-    # concurrent invocations stay shared-nothing.
-    #
-    # Sealing and the reject-after-install guard are governed by the owning
-    # Sandbox through +Catalog::Services#sealed?+, the shared seal signal;
-    # this registry only records entries and enforces the Extension-shape
-    # and dependency rules.
-    class Extensions
+    # The installed Extensions, composed onto the Service and snippet
+    # registries. Providers resolve afresh for each invocation and are handed
+    # back rather than stored, so concurrent invocations share nothing.
+    class Extensions # :nodoc:
       def initialize
         @entries = [] # : Array[untyped]
         @asserted = false
       end
 
-      # Install +extension+: validate its shape, register its +source+ as a
-      # preloaded snippet, and — when it carries a +backend+ — reserve the
-      # backend path in +services+. A static +object:+ binds directly; a
-      # per-invocation +provider:+ or a fillable backend reserves the path with
-      # +Kobako::Unresolved+ (the per-invocation result is layered onto the
-      # Context, a fillable stays Unresolved until filled). Raises
-      # +ArgumentError+ for the two shapes +#validate!+ owns — +source+ not a
-      # String, or a present +backend+ that omits +path+ / +object+ /
-      # +provider+. The Extension readers are duck-typed, so an object missing
-      # them surfaces the underlying +NoMethodError+, and a malformed +name+ or
-      # +backend.path+ surfaces through the +snippets+ / +services+
-      # registration it routes to.
+      # 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)
         snippets.register(code: extension.source, name: extension.name)
@@ -44,27 +24,24 @@ module Kobako
         self
       end
 
-      # Assert every installed Extension's +depends_on+ names a fellow
-      # installed Extension. Runs once, when the Sandbox first seals
-      # successfully; an unmet dependency raises +ArgumentError+ naming the
-      # gap, before the guest runs. The asserted flag flips only on success,
-      # so a seal that failed re-checks on the next attempt rather than
-      # silently passing a broken Sandbox. Idempotent across later invocations.
-      def seal!
+      # 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!
         return self if @asserted
 
-        assert_dependencies!
+        extension, dependency = unmet_dependency
+        if extension
+          raise ArgumentError,
+                "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
+        end
+
         @asserted = true
         self
       end
 
-      # Resolve each +provider:+-backed path to this invocation's object and
-      # return the +path => object+ map the driving +Context+ layers over the
-      # static base bindings. Distinct providers yield distinct objects; one
-      # provider shared by several Extensions is invoked once and its result
-      # shared, so provider identity is resource identity. Static and fillable
-      # backends are omitted — they stay the object bound at install in the
-      # base registry (+Kobako::Unresolved+ for a fillable).
+      # One provider shared by several Extensions is invoked once and its
+      # result shared, so provider identity is resource identity.
       def resolve
         resolved = {} # : Hash[String, untyped]
         by_provider = {} # : Hash[untyped, untyped]
@@ -75,15 +52,8 @@ module Kobako
 
       private
 
-      # The object a backend binds at install: a static +object:+ directly, or
-      # +Kobako::Unresolved+ as the placeholder for a per-invocation +provider:+
-      # (layered onto the Context) or a fillable (neither keyword).
       def install_object(backend) = backend.object.nil? ? Kobako::Unresolved : backend.object
 
-      # Resolve one Extension's +provider:+-backed path against the shared
-      # per-invocation identity cache (keyed by provider identity) and record
-      # it in +resolved+. A static or fillable backend is skipped — its object
-      # stays as bound at install in the base registry.
       def resolve_backend(extension, resolved, by_provider)
         backend = extension.backend
         return unless backend
@@ -94,9 +64,6 @@ module Kobako
         resolved[backend.path.to_s] = by_provider.fetch(provider) { by_provider[provider] = provider.call }
       end
 
-      # Enforce the Extension-shape checks +#preload+ / +#bind+ do not: a
-      # mandatory String +source+ (the install/bind boundary) and a
-      # +backend+ that, when present, exposes +path+ / +object+ / +provider+.
       def validate!(extension)
         source = extension.source
         raise ArgumentError, "Extension #source must be a String, got #{source.class}" unless source.is_a?(String)
@@ -108,21 +75,16 @@ module Kobako
         raise ArgumentError, "Extension #backend must expose #path, #object, and #provider"
       end
 
-      def assert_dependencies!
+      def unmet_dependency
         names = @entries.map { |extension| symbolize(extension.name) }
         @entries.each do |extension|
           (extension.depends_on || []).each do |dependency|
-            next if names.include?(symbolize(dependency))
-
-            raise ArgumentError,
-                  "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
+            return [extension, dependency] unless names.include?(symbolize(dependency))
           end
         end
+        nil
       end
 
-      # Match names and dependencies by Symbol so the Symbol-or-String forms
-      # of a constant token are interchangeable; a value that is neither
-      # falls through unchanged to the not-installed path.
       def symbolize(name) = name.is_a?(String) ? name.to_sym : name
     end
   end

data/lib/kobako/catalog/flags.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Catalog
+    class Flags # :nodoc:
+      def initialize
+        @entries = {} # : Hash[String, [String, bool]]
+      end
+
+      # Each entry is the name, the value, and whether the flag is critical.
+      def entries
+        @entries.map { |name, (value, critical)| [name, value, critical] }
+      end
+
+      def register(name, value, advisory:)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise ArgumentError, "flag name must be a Symbol or String, got #{name.class}"
+        end
+        raise ArgumentError, "flag value must be a String, got #{value.class}" unless value.is_a?(String)
+
+        key = utf8!(name.to_s, "flag name")
+        raise ArgumentError, "flag #{key.inspect} already set" if @entries.key?(key)
+
+        @entries[key] = [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/handles.rb

@@ -7,30 +7,11 @@ require_relative "../transport/exposure"
 
 module Kobako
   module Catalog
-    # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-    # Each invocation's +Kobako::Context+ mints its own table and hands it to
-    # the dispatcher, so guest→host dispatch resolves Handle targets and
-    # arguments against the same table that host→guest wire encoding allocates
-    # into for that run.
-    #
-    # Lifecycle invariants:
-    #
-    #   - Handle IDs are allocated by a monotonically increasing counter
-    #     scoped to a single invocation. The first ID issued in an
-    #     invocation is 1; ID 0 is reserved as the invalid sentinel and is
-    #     never returned by +#alloc+.
-    #
-    #   - A fresh table backs each invocation, so a Handle issued in one
-    #     invocation resolves in no other — uniformly regardless of
-    #     allocation source (Service return or host-injected argument).
-    #
-    #   - The cap is +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap
-    #     raises immediately — no silent truncation, no wrap, no ID reuse.
-    class Handles
-      # Build a fresh, empty table. +next_id+ is an internal seam that
-      # sets the starting value of the monotonic counter (defaults to 1);
-      # tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
-      # the cap-exhaustion path without 2³¹ allocations.
+    # One invocation's Handle table, mapping opaque ids to host objects. Each
+    # invocation mints its own, so a Handle resolves only where it was issued.
+    class Handles # :nodoc:
+      # +next_id+ lets tests start near +Kobako::Handle::MAX_ID+ to reach
+      # exhaustion without 2³¹ allocations.
       def initialize(next_id: 1)
         @entries = {} # : Hash[Integer, Kobako::Transport::Exposure]
         surfaces = {} # : Hash[Module, Set[Symbol]]
@@ -38,19 +19,6 @@ module Kobako
         @next_id = next_id
       end
 
-      # Bind +object+ in the table and return a +Kobako::Handle+ token
-      # for it. +object+ is any host-side Ruby object to bind. Returns a
-      # freshly-allocated +Kobako::Handle+ whose +#id+ falls in
-      # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
-      # +Kobako::HandleExhaustedError+ if the next ID would exceed the
-      # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
-      # and the allocator share the same invariant.
-      #
-      # Returning a Handle (rather than a bare Integer id) keeps the
-      # allocator's output a domain entity. An id is the Handle's only
-      # content, so the same internal +Kobako::Handle.restore+ constructor
-      # serves both this allocator and the codec's wire-decode path.
-      #
       # The entry records the object's Exposure as it stands at mint, so a
       # call made through this Handle is authorized against the reference
       # the guest was given.
@@ -63,27 +31,17 @@ module Kobako
         Kobako::Handle.restore(id)
       end
 
-      # Resolve a Handle ID to its bound object — the very object +#alloc+
-      # received, so a Handle crossing back restores to it. +id+ is a Handle
-      # ID previously returned by +#alloc+. Raises +Kobako::SandboxError+ if
-      # +id+ is not currently bound.
       def fetch(id)
         exposure(id).object
       end
 
-      # The Exposure +id+ was minted with, which authorizes a call the guest
-      # makes through that Handle. Raises +Kobako::SandboxError+ if +id+ is
-      # not currently bound.
       def exposure(id)
         require_bound!(id)
         @entries[id]
       end
 
-      # Number of currently-bound entries. Used by tests of the Dispatcher
-      # and Codec::HandleWalk#deep_wrap to observe whether each path allocates
-      # exactly the Handle entries it should — the +Handles+ table itself never
-      # consults its own size, but the surrounding code's allocation
-      # contract is part of the observable boundary.
+      # The table never consults its own size; tests read it to pin how many
+      # Handles each path allocates.
       def size
         @entries.size
       end
@@ -113,8 +71,6 @@ module Kobako
         end
       end
 
-      # Guard #alloc against issuing an ID past the cap. Returns +nil+
-      # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
@@ -124,9 +80,6 @@ module Kobako
               "in a single invocation (limit #{cap})"
       end
 
-      # Single source of truth for the "unknown Handle id" raise used by
-      # #fetch. Returns +nil+ on success; raises +Kobako::SandboxError+
-      # when +id+ is not currently bound.
       def require_bound!(id)
         return if @entries.key?(id)