kobako 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c3d1c75e0967f01b1284848372d66adda8cc65566b828bb1634f1624b1b4938
-  data.tar.gz: 223e0cc856970daf5c702775c1a3df2851d96beb72db1793e24c776747205a0c
+  metadata.gz: aa120ba374ca1b1ca531a99218645f73bca5bdf157fa40c053f4ee13297ac38e
+  data.tar.gz: 244a2791399621ba863fd23796c2b93bbd29a81606e48e700d51cdad140f968a
 SHA512:
-  metadata.gz: 4b6050756d4ed75616ea4aa82fe56febc11cc97c8b1cba165c607e70b6921dfad322c1594746b3e105338653fce93f5e208b4f2516c39f2f3cb4d9b85647b79b
-  data.tar.gz: 8c50704f755219097efdd41c5e47ba304fa98fe8843e5f39ee49df4c22cac7d7916cd8a96be472ffae3535d4f285422e0cca81917c722584b44165f262611212
+  metadata.gz: 58093ae0a28a1018af3479465647ea5ef5eaf61aadfdbc42cbcd7904d310015363d7aa414bf6d4073b06967d878dcce139327329cb7e9c9d21e4ce9abe2ab22b
+  data.tar.gz: 22bd8b84e48e2d49f27202353998cf80d207b2f3e0c4ae748cd95676f4a444c6d69623a87412c94cbe9658b0b08741b8f11c85d10a13371639c1d669075a53de

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.20.0","wasm/kobako-core":"0.12.0","wasm/kobako-mruby":"0.12.0","wasm/kobako-io":"0.12.0","wasm/kobako-json":"0.12.0","wasm/kobako-regexp":"0.12.0","wasm/kobako-baker":"0.12.0","crates/kobako-codec":"0.12.0","crates/kobako-runtime":"0.12.0","crates/kobako-wasmtime":"0.12.0","crates/kobako":"0.12.0"}
+{".":"0.21.0","wasm/kobako-core":"0.13.0","wasm/kobako-mruby":"0.13.0","wasm/kobako-io":"0.13.0","wasm/kobako-json":"0.13.0","wasm/kobako-regexp":"0.13.0","wasm/kobako-baker":"0.13.0","crates/kobako-transport":"0.13.0","crates/kobako-codec":"0.13.0","crates/kobako-runtime":"0.13.0","crates/kobako-wasmtime":"0.13.0","crates/kobako":"0.13.0"}

data/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## [0.21.0](https://github.com/elct9620/kobako/compare/v0.20.0...v0.21.0) (2026-07-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **spec:** speak one word for the arm every envelope answers success on
+* **transport:** let every envelope spell its success arm the same way
+* **spec:** separate what a name promises from what the wire promises
+* **sdk:** keep the root to what every build of this crate has
+* **sdk:** make the wasm engine something a host can actually take out
+* **mruby:** name each codec method after the position it serves
+* **wasmtime:** put every cap in one struct, named the way the field is read
+* **runtime:** give the engine contract names an implementer can write
+* **transport:** name the core envelope's types after what they carry
+* **guest:** make a parked block and its wire bit one statement
+* **sdk:** reach a result's host object without a schema
+* **guest:** let the shell ask for the codec instead of inheriting it
+* **customization:** the harness carries no codec until a shell asks
+* **sdk:** make the payload codec an optional dependency
+* **wire:** carry a Reply's fault arm on the envelope
+* **wire:** move the Reply's fault arm onto the envelope
+* **transport:** split the invocation module along the line its doc draws
+* **wire:** route every tier through the one envelope
+* **gem:** follow Ruby's own convention for what an error is called
+* **guest:** name the payload seam for what it is — a codec
+* **wire:** keep a Fault to what its author can bound
+* **wire:** give the fault concept one name on both sides of the boundary
+* **guest:** let the shell name the schema its guest speaks
+* **guest:** route a dispatch through kobako-core without reading its payload
+* **outcome:** raise an unresolved entrypoint as its own error carrying the names it could have been
+* **outcome:** keep a Panic's attribution when its diagnostics are unreadable
+* **wire:** carry the Outcome over the core envelope
+* **wire:** carry the Yield Reply over the core envelope
+* **wire:** carry the Run envelope over the core envelope
+* **wire:** carry the invocation frames over the core envelope
+* **codec:** make the MessagePack adapter an optional feature
+* **wire:** carry dispatch over the core envelope with an opaque payload
+
+### Features
+
+* **bench:** measure the host's per-invocation cost against a null guest ([c60abdf](https://github.com/elct9620/kobako/commit/c60abdfc98a38b03a4a598913df9a1120ed6302b))
+* **bench:** move the two host-side benchmarks into the gated set ([31a6f7e](https://github.com/elct9620/kobako/commit/31a6f7ebb40c038b39c38ee2441216a412be48d0))
+* **codec:** make the MessagePack adapter an optional feature ([effff27](https://github.com/elct9620/kobako/commit/effff278fd220a4d3c8d4e857828d610fe01f48e))
+* **guest:** let the shell name the schema its guest speaks ([5ad2e0d](https://github.com/elct9620/kobako/commit/5ad2e0db4c645ab56153a81d1623e37e8cd8f5c6))
+* **guest:** open the block seam to a capability gem ([c6d6e49](https://github.com/elct9620/kobako/commit/c6d6e49013bd0f850dd4f2c17273103f166294c2))
+* **outcome:** keep a Panic's attribution when its diagnostics are unreadable ([8accd40](https://github.com/elct9620/kobako/commit/8accd404c9d9155f19fa0458d7e0650b5d587eb1))
+* **outcome:** raise an unresolved entrypoint as its own error carrying the names it could have been ([05b4125](https://github.com/elct9620/kobako/commit/05b41257ca8d4bcb90d6759c6cc7b20582af0661))
+* **sdk:** let a host bring its own wasm engine ([70c2475](https://github.com/elct9620/kobako/commit/70c24759ef4cd5785bd1418a6f8d199620f59e2b))
+* **sdk:** make the payload codec an optional dependency ([0c7da71](https://github.com/elct9620/kobako/commit/0c7da71bfc0b138a316c9612b23b2944684d652e))
+* **sdk:** make the wasm engine something a host can actually take out ([c9f8de6](https://github.com/elct9620/kobako/commit/c9f8de662e6dcd31c8444d9424b1a87ca144f1a6))
+* **sdk:** reach a result's host object without a schema ([a0a2c56](https://github.com/elct9620/kobako/commit/a0a2c56ca5efe8daded876cdcfb8cf0ec8dd4e77))
+* **spec:** anchor what a guest does at a position its codec does not serve ([3a084ea](https://github.com/elct9620/kobako/commit/3a084ea3c60c193038b6dd06d191b14d2ccde4f1))
+* **tasks:** gate signatures against declarations the code dropped ([8b1b834](https://github.com/elct9620/kobako/commit/8b1b834664a51ed6330ba77e9cc3fb7cc4490faf))
+* **tasks:** gate the benchmark probes on still running ([31c3455](https://github.com/elct9620/kobako/commit/31c345534c36f49670075fbfdecff645314d6d24))
+* **wire:** carry a Reply's fault arm on the envelope ([0bce850](https://github.com/elct9620/kobako/commit/0bce850b3416696e92ae6ee12c353c4c21c8e583))
+* **wire:** carry dispatch over the core envelope with an opaque payload ([556104b](https://github.com/elct9620/kobako/commit/556104bf86fdf481b5368b70af83eb0add4b2708))
+* **wire:** carry the invocation frames over the core envelope ([b6f266a](https://github.com/elct9620/kobako/commit/b6f266a310ff723a1868cff745763d91c0603a5e))
+* **wire:** carry the Outcome over the core envelope ([3fa338e](https://github.com/elct9620/kobako/commit/3fa338e4e03b16c4f25f903f1d45f672ab1d015d))
+* **wire:** carry the Run envelope over the core envelope ([d7c46ab](https://github.com/elct9620/kobako/commit/d7c46ab64e382f5226c780b39c8bb66ee12213ac))
+* **wire:** carry the Yield Reply over the core envelope ([0db7261](https://github.com/elct9620/kobako/commit/0db726189adbc369e32b569cd191861dbba17302))
+
+
+### Bug Fixes
+
+* **bench:** bound and surface the band the archive widens ([cc2ddd2](https://github.com/elct9620/kobako/commit/cc2ddd213d8f9382c9b7ff20581abd2b171fe486))
+* **bench:** let probe discovery reach any depth ([2a164ca](https://github.com/elct9620/kobako/commit/2a164cab782a51e9d15b522f8a2c340b5f234b9a))
+* **bench:** name only the rows the archive actually sets the bar for ([68e167f](https://github.com/elct9620/kobako/commit/68e167f56c801ad4b9caf7f290824d28f216aec9))
+* **bench:** sample the cold-start row's guest budget instead of observing it once ([95bdadd](https://github.com/elct9620/kobako/commit/95bdadde1f81fb169293c89cbccd460fb0c6e502))
+* **bench:** widen the gate's noise band by what the archive shows ([183407c](https://github.com/elct9620/kobako/commit/183407cfc3854c1179f7c5b7da338d2295526bfc))
+* **build:** rebuild the guest when the fixed tier changes ([037cc2e](https://github.com/elct9620/kobako/commit/037cc2e9451fbf34bd2138abfbc8b9b59fd613cc))
+* **ext:** name the Panic attribution tuple and drop two lint carries ([ab24625](https://github.com/elct9620/kobako/commit/ab24625233c3559c9b3c737182d6614a4e03926b))
+* **guest:** make a parked block and its wire bit one statement ([dba5625](https://github.com/elct9620/kobako/commit/dba5625c541c9b54caa89f5937419ec416ec05a8))
+* **guest:** read a String's bytes instead of rendering it ([de8c238](https://github.com/elct9620/kobako/commit/de8c238e900830f72d374f83d8c8e5b63cef4384))
+* **guest:** refuse text the capability gems cannot read as text ([539045a](https://github.com/elct9620/kobako/commit/539045a80192cc28c23a4bcbebc311c55eb138fb))
+* **payload:** stop claiming a zero-copy decode the args position cannot have ([c56cb9c](https://github.com/elct9620/kobako/commit/c56cb9c30dc727d9ad0510e3f1572c1ab53463d9))
+* **release:** drop the version from a dev-dependency nothing rewrites ([524e536](https://github.com/elct9620/kobako/commit/524e5365448fedb101571a11de546dddebbfbcb6))
+* **sig:** declare the dispatch seam the shape the ext actually calls ([f0de465](https://github.com/elct9620/kobako/commit/f0de46500eda366d3edd7869edcc39d843f4b687))
+* **sig:** drop the Pool method the signature outlived ([35a5b4f](https://github.com/elct9620/kobako/commit/35a5b4ff3e834b157d695819272c2b445f0bb5bf))
+* **tasks:** let a retired anchor hold the ceiling it was assigned ([a9cd51d](https://github.com/elct9620/kobako/commit/a9cd51d2bd454698833024c89c3693b0d73ef505))
+* **wire:** keep the ABI at 3, which no release has shipped ([2b301b7](https://github.com/elct9620/kobako/commit/2b301b777384c0edf79426805cfb1cc08688aa95))
+
+
+### Documentation
+
+* **customization:** the harness carries no codec until a shell asks ([a9bf10c](https://github.com/elct9620/kobako/commit/a9bf10c20f27f52183932dd149768626d70f31bf))
+* **spec:** separate what a name promises from what the wire promises ([545bfbd](https://github.com/elct9620/kobako/commit/545bfbd59834bab6d564850d9adafa892cbae005))
+* **spec:** speak one word for the arm every envelope answers success on ([f4ef5f5](https://github.com/elct9620/kobako/commit/f4ef5f5c096cb2c5b0153f7a28f7feaf15a405d0))
+* **wire:** move the Reply's fault arm onto the envelope ([3a56e89](https://github.com/elct9620/kobako/commit/3a56e892caea5b2024baeeeff0bcb8b0169e9b16))
+
+
+### Code Refactoring
+
+* **gem:** follow Ruby's own convention for what an error is called ([b1ce1fe](https://github.com/elct9620/kobako/commit/b1ce1fe994e5123a950ba9b9f64810387822bb46))
+* **guest:** let the shell ask for the codec instead of inheriting it ([abc24d3](https://github.com/elct9620/kobako/commit/abc24d3321c614f36f8c01c932169083796a0915))
+* **guest:** name the payload seam for what it is — a codec ([b5d90e2](https://github.com/elct9620/kobako/commit/b5d90e26cdea1e0048cb44e48c6543a6bad4a592))
+* **guest:** route a dispatch through kobako-core without reading its payload ([62c5791](https://github.com/elct9620/kobako/commit/62c5791eb88b9021b3d60c8a3dd45d5907011214))
+* **mruby:** name each codec method after the position it serves ([e2d4b53](https://github.com/elct9620/kobako/commit/e2d4b53dd2d165d4f6312c8e87a5dd936d2f7a2f))
+* **runtime:** give the engine contract names an implementer can write ([0a41491](https://github.com/elct9620/kobako/commit/0a41491360cf17def8245c0758679e92572b990f))
+* **sdk:** keep the root to what every build of this crate has ([7f93096](https://github.com/elct9620/kobako/commit/7f93096d4371e7e7f70f3b31301fad3a3198184a))
+* **transport:** let every envelope spell its success arm the same way ([df595e0](https://github.com/elct9620/kobako/commit/df595e08097af9e3e0a0c5ed52a4a6f854eb21dc))
+* **transport:** name the core envelope's types after what they carry ([b44de65](https://github.com/elct9620/kobako/commit/b44de6502953826c567d4ef8a594561479f50c1d))
+* **transport:** split the invocation module along the line its doc draws ([4d3a2d3](https://github.com/elct9620/kobako/commit/4d3a2d3060167d71a807e203688186740fd1485b))
+* **wasmtime:** put every cap in one struct, named the way the field is read ([3f57860](https://github.com/elct9620/kobako/commit/3f578608b044d1ade0ae35231266cf3c9e517c02))
+* **wire:** give the fault concept one name on both sides of the boundary ([564798a](https://github.com/elct9620/kobako/commit/564798a9662f547f665530a75d99c73051a79d86))
+* **wire:** keep a Fault to what its author can bound ([141209d](https://github.com/elct9620/kobako/commit/141209df0f5525853462fddcfaf3584ea530038b))
+* **wire:** route every tier through the one envelope ([c5cd33a](https://github.com/elct9620/kobako/commit/c5cd33a5346f49857fa6e1f45c9cf9b9bea0ff77))
+
 ## [0.20.0](https://github.com/elct9620/kobako/compare/v0.19.0...v0.20.0) (2026-07-24)
 
 

data/Cargo.lock

@@ -929,9 +929,10 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.20.0"
+version = "0.21.0"
 dependencies = [
  "kobako-runtime",
+ "kobako-transport",
  "kobako-wasmtime",
  "magnus",
  "rb-sys",
@@ -939,13 +940,21 @@ dependencies = [
 
 [[package]]
 name = "kobako-runtime"
-version = "0.12.0"
+version = "0.13.0"
+dependencies = [
+ "kobako-transport",
+]
+
+[[package]]
+name = "kobako-transport"
+version = "0.13.0"
 
 [[package]]
 name = "kobako-wasmtime"
-version = "0.12.0"
+version = "0.13.0"
 dependencies = [
  "kobako-runtime",
+ "kobako-transport",
  "libc",
  "sha2 0.11.0",
  "wasmtime",

data/README.md

@@ -14,9 +14,10 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
    │  Services            │ ◀─call─ │  KV::Lookup.call(k)  │
    │   KV::Lookup         │ ─resp─▶ │                      │
    │                      │         │                      │
-   │  stdout / stderr buf │ ◀─pipe─ │  puts / warn         │
-   │                      │         │                      │
-   │  return value        │ ◀─last─ │  last expression     │
+   │  Execution           │ ◀─pipe─ │  puts / warn         │
+   │   value              │ ◀─last─ │  last expression     │
+   │   stdout / stderr    │         │                      │
+   │   usage              │         │                      │
    └──────────────────────┘         └──────────────────────┘
             trusted                       untrusted
 ```
@@ -45,23 +46,27 @@ The same untrusted script runs identically from either host frontend. It execute
 require "kobako"
 
 sandbox = Kobako::Sandbox.new
-sandbox.eval("1 + 2")  # => 3
+sandbox.eval("1 + 2").value  # => 3
 ```
 
 ```rust
 use kobako::{Options, Sandbox};
 
 // Options::default() is secure by default: no caps, hermetic isolation.
-let mut sandbox = Sandbox::new("kobako.wasm", Options::default())?;
-sandbox.eval("1 + 2")?;  // => Value::Int(3)
+let sandbox = Sandbox::new("kobako.wasm", Options::default())?;
+sandbox.eval("1 + 2")?.value()?;  // => Value::Int(3)
 ```
 
+Each invocation returns the record of that one run — `Kobako::Execution` in Ruby, `Execution` in Rust — carrying the guest value alongside the run's output and resource usage. Nothing a run observes is stored on the Sandbox, so the same Sandbox serves concurrent invocations without them seeing each other.
+
 The gem bundles its Guest Binary; a Rust host loads one explicitly — see [Frontends & Guest Binaries](#frontends--guest-binaries) for the packages and the Guest Binary variants.
 
 ## Frontends & Guest Binaries
 
 Embedding kobako is two independent choices: the **host frontend** you build against, and the **Guest Binary** it runs. They compose freely — any frontend loads any Guest Binary, so a Ruby host can run a JSON-enabled guest and a Rust host can run the pure default.
 
+How far down those choices go — and which ones a given starting point quietly makes for you — is laid out in [`docs/architecture.md`](docs/architecture.md).
+
 ### Host frontends
 
 The host embeds the sandbox and owns the SPEC wire codec. Choose by your host language and how much of the contract you want pre-assembled.
@@ -69,8 +74,8 @@ The host embeds the sandbox and owns the SPEC wire codec. Choose by your host la
 | Frontend | Package | Add it | Best for |
 |----------|---------|--------|----------|
 | Ruby gem | `kobako` (RubyGems) | `gem install kobako` | A Ruby host — Services, Handles, snippets, and pooling out of the box |
-| Rust SDK | `kobako` (crates.io) | `kobako = "0.9"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
-| Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-codec` | Cargo deps | A custom host, or driving the wire directly in another language |
+| Rust SDK | `kobako` (crates.io) | `kobako = "0.12"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
+| Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-transport` + `kobako-codec` | Cargo deps | A custom host, or driving the wire directly in another language |
 
 The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Two runnable Rust hosts show the choice: [`plugin-rs`](examples/plugin-rs) builds on the SDK, and [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates.
 
@@ -88,7 +93,7 @@ The gem bundles the pure `kobako.wasm`. Regexp and JSON are opt-in capabilities
 
 ```ruby
 sandbox = Kobako::Sandbox.new(wasm_path: "kobako+full.wasm")
-sandbox.eval('JSON.generate({ n: "42".to_i })')  # => "{\"n\":42}"
+sandbox.eval('JSON.generate({ n: "42".to_i })').value  # => "{\"n\":42}"
 ```
 
 ### Custom Guest Binaries
@@ -133,9 +138,11 @@ Build the crate as a `cdylib` for `wasm32-wasip1`, then bake the canonical boot
 
 | Term | Meaning |
 |------|---------|
-| Sandbox | The runtime unit (`Kobako::Sandbox`) that runs guest code and returns a result or raises a typed error. |
+| Sandbox | The reusable unit (`Kobako::Sandbox`) that runs guest code and returns a result or raises a typed error. It holds configuration only — no state from any run. |
 | Service | A host object bound at a constant-path name (`MyService::KV`) — the guest's only path to host resources. |
-| Invocation | One `#eval` or `#run`; capability state resets between invocations. |
+| Invocation | One `#eval` or `#run`; capability state is scoped to it and ends with it. |
+| Execution | The frozen record one invocation returns (`Kobako::Execution`): its `#value`, output captures, and `#usage`. A failed run raises, carrying the same record on the error's `#execution`. |
+| Context | The per-invocation object the optional `#eval` / `#run` block receives; its `ctx.bind` supplies a Service object for that one run. |
 | Snippet | Named mruby code (source or bytecode) replayed into a fresh state before every invocation. |
 | Handle | An opaque token the guest holds for a host object the wire cannot transmit directly. |
 | Block | A guest mruby block passed to a Service; each `yield` is a synchronous round-trip into the guest. |
@@ -166,25 +173,37 @@ RUBY
 
 Each `::`-separated path segment must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation (see [Invocation Lifecycle](#invocation-lifecycle)); later `#bind` raises `ArgumentError`.
 
+### Per-Invocation Bindings
+
+A setup-time `bind` fixes one object for the Sandbox's life. When the object belongs to a single run instead — the current request, the acting user, a per-tenant store — declare the path at setup and fill it per invocation. `bind(path)` with no object reserves the name as a *fillable*: the guest sees the constant, while an unfilled dispatch fails closed as `Kobako::ServiceError`. The optional `#eval` / `#run` block fills it ([`docs/behavior/registration.md`](docs/behavior/registration.md) B-62..B-63).
+
+```ruby
+sandbox.bind("Req::Current")  # declared, unfilled — stands for Kobako::Unresolved
+
+sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
+```
+
+`ctx.bind` also shadows an already-bound path for that one run. The Context is spent once the block returns, so a `ctx` captured out of it raises `ArgumentError`. Choosing the object per invocation instead of sharing one is what lets concurrent Threads invoke a single Sandbox and still keep their identities apart — the [multi-tenant example](examples/multi-tenant/) runs that shape end to end.
+
 ### Output Capture
 
-Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
+Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and read off the run's Execution, independently of its `#value` ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-04). Each invocation captures its own; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
 ```ruby
-result = sandbox.eval(<<~RUBY)
+execution = sandbox.eval(<<~RUBY)
   puts "hello"
   warn "be careful"
   42
 RUBY
 
-result          # => 42
-sandbox.stdout  # => "hello\n"
-sandbox.stderr  # => "be careful\n"
+execution.value   # => 42
+execution.stdout  # => "hello\n"
+execution.stderr  # => "be careful\n"
 ```
 
 ### Error Handling
 
-Every invocation either returns a value or raises exactly one of three classes, so you can route faults without inspecting messages. The full taxonomy lives in [`lib/kobako/errors.rb`](lib/kobako/errors.rb).
+Every invocation either returns an Execution or raises exactly one of three classes, so you can route faults without inspecting messages. The full taxonomy lives in [`lib/kobako/errors.rb`](lib/kobako/errors.rb).
 
 ```ruby
 begin
@@ -193,23 +212,27 @@ rescue Kobako::TrapError
   # Wasm engine fault or cap exhaustion. Discard the Sandbox.
 rescue Kobako::ServiceError
   # A host Service call failed and the script did not rescue it.
-rescue Kobako::SandboxError
+rescue Kobako::SandboxError => e
   # The script raised, failed to compile, or returned an unrepresentable value.
+  logger.warn(e.execution.stderr)  # the failed run's own captures and usage
 end
 ```
 
+Each of these carries the failed run's Execution on `#execution`, so a rescue reads that run's output and usage exactly as a successful caller reads them off the returned one. `#failed?` keeps the two apart when both `#value` are `nil` — a script whose last expression was `nil` versus one that never produced a value. A failure caught before the guest ran at all — a host pre-flight refusal — leaves `#execution` `nil`, since there is no run to report.
+
 | Class                           | Parent         | Trigger                                              |
 |---------------------------------|----------------|------------------------------------------------------|
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
 | `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
+| `Kobako::UndefinedEntrypointError` | `SandboxError` | `#run` named a constant no snippet defined; carries `#name` and `#available` |
 
-`SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.
+`SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` fields when the guest produced a panic envelope.
 
 ### Resource Limits
 
-Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-35).
+Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Execution#usage`](lib/kobako/execution.rb) for actual consumption — populated on every outcome, so a rescued trap reports it just as a completed run does ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-35).
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
@@ -229,17 +252,30 @@ sandbox = Kobako::Sandbox.new(
 
 `memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
 
-A fifth option, `profile:`, requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources — an explicit trade of reproducibility, with filesystem, environment, and network still unreachable. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/security-model.md`](docs/security-model.md) § Isolation profiles.
+Beyond the four caps, `profile:` requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources — an explicit trade of reproducibility, with filesystem, environment, and network still unreachable. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/security-model.md`](docs/security-model.md) § Isolation profiles.
+
+### Concurrency
+
+A Sandbox keeps no state from any run, so concurrent Threads may invoke distinct Sandboxes or share a single one; each invocation owns its Handles, captures, and usage either way ([`docs/behavior/runtime.md`](docs/behavior/runtime.md) B-22). One Thread still runs one invocation at a time. Sharing a Sandbox adds a single obligation: an object bound once at setup is reached by every Thread and must itself be thread-safe, while an object supplied per invocation — `ctx.bind`, or an Extension `provider:` — carries no such requirement.
+
+By default an invocation holds Ruby's GVL for its whole span, so guest execution across Threads serializes. `gvl: :release` drops the GVL for the guest span and re-acquires it for each guest→host dispatch, running guest code in parallel across Threads (B-64).
+
+```ruby
+sandbox = Kobako::Sandbox.new(gvl: :release)
+```
+
+The mode is per-Sandbox and fixed at construction; it changes scheduling only, leaving isolation, Handle lifetimes, captures, and outcomes identical. `:hold` remains the default because releasing pays a handoff cost at every dispatch: compute-bound scripts scale with Thread count, while dispatch-heavy ones match or trail `:hold`. `rake bench:gvl_scheduling` measures both ends on your own hardware.
 
 ### Invocation Lifecycle
 
-One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; capability state (Handles, stdout, stderr, memory delta) resets between them.
+One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; everything a run produces — Handles, captured output, memory delta — belongs to that run alone.
 
 ```
    ───────────── setup phase (mutable) ─────────────
 
      sandbox = Kobako::Sandbox.new
      sandbox.bind("KV::Lookup", ...)
+     sandbox.bind("Req::Current")          # fillable: object comes later
      sandbox.preload(code: ..., name: :Adder)
      sandbox.preload(code: ..., name: :Greeter)
 
@@ -256,20 +292,24 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
    ──────────────── invocation N ───────────────────
 
-     1. start from the canonical boot state
+     1. resolve this run's bindings, before the guest starts:
+          ctx.bind("Req::Current", ...)  fills the fillable
+          provider: backends yield this run's object
+
+     2. start from the canonical boot state
         (mruby pre-initialized into the artifact at build time)
 
-     2. replay snippets (in insertion order):
+     3. replay snippets (in insertion order):
           :Adder     → defines Adder
           :Greeter   → defines Greeter
 
-     3. dispatch:  eval(source)  or  run(:Target, *args, **kwargs)
+     4. dispatch:  eval(source)  or  run(:Target, *args, **kwargs)
 
-     4. return value to host
+     5. return the run's Execution to host
 
-     5. discard the instance; reset per-invocation state:
+     6. discard the instance; per-invocation state ends with it:
           · Handles invalidated
-          · stdout / stderr buffers cleared
+          · captures frozen into the Execution
           · memory delta zeroed
 
      Services + snippets persist; invocation N+1 repeats.
@@ -281,14 +321,14 @@ For workloads that must be isolated from each other (one Sandbox per tenant, per
 
 For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`docs/behavior/runtime.md`](docs/behavior/runtime.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
 
-`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the ~28 µs host-side `Sandbox.new`. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a significant gain (~4-5% in the [serverless example](examples/serverless/README.md), and proportionally less once the script itself does real work).
+`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the ~28 µs host-side `Sandbox.new`. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a significant gain (~4-5% in the [serverless example](examples/serverless/README.md), and proportionally less once the script itself does real work). What a Pool buys is warm setup and exclusive checkout, not isolation: a Sandbox holds no state from any run, so Threads sharing one are equally safe (see [Concurrency](#concurrency)).
 
 ```ruby
 pool = Kobako::Pool.new(slots: 4) do |sandbox|
   sandbox.bind("KV::Lookup", ->(key) { redis.get(key) })
 end
 
-pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))) }
+pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))).value }
 ```
 
 | Option | Meaning | Default |
@@ -296,7 +336,7 @@ pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))) }
 | `slots:` | Upper bound on constructed Sandboxes | required |
 | `checkout_timeout:` | Seconds `#with` waits for a free Sandbox; `nil` waits indefinitely | 5.0 |
 
-Sandboxes construct lazily on first demand. `#with` yields a Sandbox with empty output buffers and returns the block's value; at block exit the Sandbox returns to the pool, except a block that raises `Kobako::TrapError` discards its Sandbox and the slot refills by a fresh construction on next demand. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
+Sandboxes construct lazily on first demand. `#with` yields a Sandbox and returns the block's value; at block exit the Sandbox returns to the pool, except a block that raises `Kobako::TrapError` discards its Sandbox and the slot refills by a fresh construction on next demand. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
 
 ### Service Blocks
 
@@ -305,7 +345,7 @@ A Service method can accept a guest-supplied block via `&blk` and `yield` into i
 ```ruby
 sandbox.bind("Seq::Map", ->(items, &blk) { items.map(&blk) })
 
-sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
+sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }').value
 # => [2, 4, 6]
 ```
 
@@ -321,8 +361,8 @@ end
 
 sandbox.bind("Factory::Make", ->(name) { Greeter.new(name) })
 
-sandbox.eval('Factory::Make.call("Bob").greet')  # => "hi, Bob"  (Handle round-trip inside guest)
-sandbox.eval('Factory::Make.call("Bob")')        # => #<Greeter @name="Bob">  (B-37 restoration)
+sandbox.eval('Factory::Make.call("Bob").greet').value  # => "hi, Bob"  (Handle round-trip inside guest)
+sandbox.eval('Factory::Make.call("Bob")').value        # => #<Greeter @name="Bob">  (B-37 restoration)
 ```
 
 A `break` value from a guest block is the one exception: it unwinds back to the guest Service call rather than to host code, so a Handle in it stays a Handle — restoring would just re-wrap the same object into a new id on the return trip.
@@ -351,13 +391,17 @@ This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and
 
 ```ruby
 sandbox = Kobako::Sandbox.new
-sandbox.preload(code: "Adder   = ->(a, b)  { a + b }",          name: :Adder)
-sandbox.preload(code: 'Greeter = ->(name:) { "hello, #{name}" }', name: :Greeter)
+sandbox.preload(code: "Adder   = ->(a, b) { a + b }",                    name: :Adder)
+sandbox.preload(code: 'Greeter = ->(opts) { "hello, #{opts[:name]}" }', name: :Greeter)
 
-sandbox.run(:Adder, 2, 3)            # => 5
-sandbox.run(:Greeter, name: "world") # => "hello, world"
+sandbox.run(:Adder, 2, 3).value            # => 5
+sandbox.run(:Greeter, name: "world").value # => "hello, world"
 ```
 
+An entrypoint's `kwargs` arrive as a trailing positional Hash — mruby's C-side call path carries no keyword arguments — so declare a Hash parameter and unpack it yourself.
+
+A target no snippet defined raises `Kobako::UndefinedEntrypointError`, whose `#available` lists the top-level constants the snippets did contribute — so the name is corrected from the error rather than by reading the guest source.
+
 ```
    per-invocation replay (every #eval / #run, snippets in insertion order):
 
@@ -370,7 +414,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
             └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
                        │
                        ▼
-                  return value, then instance discarded
+              return the Execution, then discard the instance
 ```
 
 `#preload` accepts two payload forms:
@@ -401,7 +445,7 @@ sandbox.install(
     source: FILE,
     backend: Kobako::Extension::Backend.new(
       path: "File",
-      provider: -> { OverlayFileSystem.new(root) }  # callable → fresh per invocation
+      provider: -> { OverlayFileSystem.new(root) }  # invoked once per invocation
     )
   )
 )
@@ -409,7 +453,15 @@ sandbox.install(
 sandbox.eval('File.read("sample.txt")')  # dispatches to the backend's #read
 ```
 
-The `backend.provider` sets the bound object's lifetime: a fixed object is shared across every invocation, while a callable is invoked once per invocation to yield a fresh object — the form a writable backend needs, so its state cannot leak across calls. kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked `File` that reads through to disk while protecting it from guest writes.
+A backend declares the bound object's lifetime by keyword, never by inference — so a static object that happens to be callable stays unambiguous.
+
+| Keyword     | Lifetime                                                                    |
+|-------------|-----------------------------------------------------------------------------|
+| `object:`   | One object, shared by every invocation                                       |
+| `provider:` | A no-argument callable invoked per invocation — what a writable backend needs, so its state cannot leak across runs |
+| neither     | A fillable, standing for `Kobako::Unresolved` until `ctx.bind` supplies the run's object |
+
+kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked `File` that reads through to disk while protecting it from guest writes.
 
 ## Security
 
@@ -425,7 +477,7 @@ end
 sandbox = Kobako::Sandbox.new
 sandbox.bind("Cfg::Settings", ThemeReader.new)  # not: bind("Cfg::Settings", AppConfig)
 
-sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
+sandbox.eval('Cfg::Settings.color').value  # => "#3366ff"  — every other method raises NoMethodError
 ```
 
 When a purpose-built wrapper is more than you need, an object can gate its own surface in
@@ -454,12 +506,12 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 | Snippet replay per invocation                                | ~7.6 µs each          |
 | Per additional idle Sandbox (RSS)                            | ~1 KB                 |
 
-The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~33 MB total. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 17k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. A +10% regression on any of the six SPEC-mandated benchmarks blocks release.
+The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~33 MB total. Under the default `gvl: :hold`, wasm work is GVL-serialized: aggregate throughput stays around 17k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. Opting a Sandbox into `gvl: :release` lifts that ceiling for compute-bound scripts (see [Concurrency](#concurrency)). A +10% regression on any SPEC-mandated benchmark blocks release.
 
 Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4× `match?` (~1.2 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
 
 ```bash
-bundle exec rake bench  # six gated regression benchmarks (~5-8 min)
+bundle exec rake bench  # every gated regression benchmark (~5-8 min)
 ```
 
 ## Development

data/ROADMAP.md

@@ -16,7 +16,7 @@ output capture, and a warm Sandbox pool.
 | ✅ [F-06 Capability Handle encoding and referencing](docs/behavior/dispatch.md) | [lib/kobako/catalog/handles.rb](lib/kobako/catalog/handles.rb) | — |
 | ✅ [F-07 Three-class error attribution and raising](docs/behavior/errors.md) | [lib/kobako/outcome.rb](lib/kobako/outcome.rb) | E-26 (guest-entry envelope decode failure) has no exercising test — not reachable through the public API |
 | ✅ [F-08 Guest output capture](docs/behavior/lifecycle.md) | [lib/kobako/capture.rb](lib/kobako/capture.rb) | — |
-| ✅ [F-09 Host–guest message codec](docs/wire-codec.md) | [lib/kobako/codec/](lib/kobako/codec/) | — |
+| ✅ [F-09 Host–guest message codec](docs/wire-codec.md) | [crates/kobako-transport/](crates/kobako-transport/) (core envelope + ABI, one implementation), [lib/kobako/codec/](lib/kobako/codec/) (host payload codec) | The payload layer has a second implementation in `crates/kobako-codec`; the envelope layer is pinned by golden vectors instead |
 | ✅ [F-10 Reproducible build pipeline](SPEC.md#code-organization) | [tasks/wasm/build.rake](tasks/wasm/build.rake) | Verified by build-time gates (`rake anchors`, double-bake byte-identity, gemspec whitelist), not `test/` |
 | ✅ [F-11 Multi-layer test and benchmark suite](SPEC.md#testing-style) | [test/](test/) | Benchmarks live in [benchmark/](benchmark/) with the gate in `tasks/bench/`; the anchor baseline advances only by deliberate re-bless |
 | ✅ [F-12 Guest block reception and yield re-entry](docs/behavior/yield.md) | [lib/kobako/transport/yielder.rb](lib/kobako/transport/yielder.rb) | — |

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.12.0...kobako-runtime-v0.13.0) (2026-07-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **runtime:** mark the sets that grow, and say why the closed ones do not
+* **spec:** separate what a name promises from what the wire promises
+* **runtime:** give the engine contract names an implementer can write
+* **sdk:** attribute an invocation without reading its payload
+* **wire:** route every tier through the one envelope
+* **outcome:** raise an unresolved entrypoint as its own error carrying the names it could have been
+* **wire:** carry dispatch over the core envelope with an opaque payload
+
+### Features
+
+* **outcome:** raise an unresolved entrypoint as its own error carrying the names it could have been ([05b4125](https://github.com/elct9620/kobako/commit/05b41257ca8d4bcb90d6759c6cc7b20582af0661))
+* **runtime:** mark the sets that grow, and say why the closed ones do not ([1be2449](https://github.com/elct9620/kobako/commit/1be24492961e2c2a3a317f784cc2f20ae584dcbf))
+* **wire:** add the core envelope, implemented independently on both peers ([e6c41d1](https://github.com/elct9620/kobako/commit/e6c41d179e5bf619d43d94160dd597c8ae3bc9bf))
+* **wire:** carry dispatch over the core envelope with an opaque payload ([556104b](https://github.com/elct9620/kobako/commit/556104bf86fdf481b5368b70af83eb0add4b2708))
+
+
+### Bug Fixes
+
+* **sig:** declare the dispatch seam the shape the ext actually calls ([f0de465](https://github.com/elct9620/kobako/commit/f0de46500eda366d3edd7869edcc39d843f4b687))
+
+
+### Documentation
+
+* **spec:** separate what a name promises from what the wire promises ([545bfbd](https://github.com/elct9620/kobako/commit/545bfbd59834bab6d564850d9adafa892cbae005))
+
+
+### Code Refactoring
+
+* **runtime:** give the engine contract names an implementer can write ([0a41491](https://github.com/elct9620/kobako/commit/0a41491360cf17def8245c0758679e92572b990f))
+* **sdk:** attribute an invocation without reading its payload ([70d22d0](https://github.com/elct9620/kobako/commit/70d22d01c79034d3d3011e95af5839d6eea654c8))
+* **wire:** route every tier through the one envelope ([c5cd33a](https://github.com/elct9620/kobako/commit/c5cd33a5346f49857fa6e1f45c9cf9b9bea0ff77))
+
 ## [0.12.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.11.0...kobako-runtime-v0.12.0) (2026-07-24)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.12.0"
+version = "0.13.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -21,3 +21,10 @@ repository = "https://github.com/elct9620/kobako"
 readme = "README.md"
 keywords = ["wasm", "mruby", "sandbox", "wasi"]
 categories = ["wasm", "virtualization"]
+
+# The fixed tier: the core envelope this contract routes and attributes
+# through. The version pin rides the linked release group; the path keeps
+# in-tree builds (and the Ruby gem, which ships both crates) resolving
+# locally.
+[dependencies]
+kobako-transport = { version = "0.13.0", path = "../kobako-transport" }

data/crates/kobako-runtime/README.md

@@ -26,7 +26,7 @@ map the neutral types onto their own language surface.
 
 ```toml
 [dependencies]
-kobako-runtime = "0.12.0" # x-release-please-version
+kobako-runtime = "0.13.0" # x-release-please-version
 ```
 
 ## License