kobako 0.9.2-x86_64-linux → 0.11.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b783a758091145f58f0a8e13b84c76c5c3a1420325ca2d272b5a58d31f7d38
-  data.tar.gz: b890067d1cc6af31a9cf74c8f3116504222ab1c64921715a3a9f35d6c60a9adb
+  metadata.gz: 88cfe63025113640b86313e0db4764e075df080db27c2d46a41f3437a9665748
+  data.tar.gz: 2fea087aa65fbf8a56ab9ac6d4cb040c02c920095e2e024894419f9094df3a62
 SHA512:
-  metadata.gz: ee3aa19299ca309a21b3ae63d3cfd38ac322c3ebd4bd0d7b8aecac2e893edfaff7cf36ec5878f0f4f42c2e1f50fa68ad5df07e38d3d27829ce442162896cf848
-  data.tar.gz: 511eeeaeeb466f7ce6b441e88cb8927de4c58da73e7596b327b5658bcffd8ccbbe6aec6877b3461d7f2de2b0eb1b544da4dedf939a37dbf340cc56cee153dd85
+  metadata.gz: eba4996867c874cfbbe5170420637f9fb8743cd68e7a5e0fc5bc63af5afbb9b8303cb3388f4808c1d6c699357a2f411e55040ef1ab23b4878c4fac3e18403063
+  data.tar.gz: e4ab4f98eff567fb86415365099d6d11e7857be4146c5fa6ac3260ca8fca1c1c9de9e1b0cfde77a3aa2a1781409ccf76d0df3116505e22f81ecc75a2069dcb9a

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.9.2","wasm/kobako-core":"0.4.1","wasm/kobako":"0.4.1","wasm/kobako-io":"0.4.1","wasm/kobako-regexp":"0.4.1"}
+{".":"0.11.0","wasm/kobako-core":"0.5.0","wasm/kobako":"0.5.0","wasm/kobako-io":"0.5.0","wasm/kobako-regexp":"0.5.0","wasm/kobako-baker":"0.5.0"}

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.11.0](https://github.com/elct9620/kobako/compare/v0.10.0...v0.11.0) (2026-06-13)
+
+
+### Features
+
+* **transport:** narrow guest-reachable methods via respond_to_guest? ([7a25fe3](https://github.com/elct9620/kobako/commit/7a25fe3b440b523b8a692b7601d08877b1305b0d))
+
+## [0.10.0](https://github.com/elct9620/kobako/compare/v0.9.2...v0.10.0) (2026-06-12)
+
+
+### Features
+
+* **catalog:** reject member binding after the seal (E-45) ([5193ed6](https://github.com/elct9620/kobako/commit/5193ed64100fa8ac05a2ba18cfa00634b4f40e6f))
+* **guest:** bake the canonical boot state and instantiate per invocation (B-49) ([ee9ae6e](https://github.com/elct9620/kobako/commit/ee9ae6e09eab30f54dba0eeec00a5a2c80da819f))
+* **pool:** add Kobako::Pool warm-Sandbox checkout (B-46..B-48) ([abf9bf8](https://github.com/elct9620/kobako/commit/abf9bf8d3c725c0ca0b8f2ab8b2ddd6f71ee6de4))
+
+
+### Bug Fixes
+
+* **ext:** give the ABI probe a WASI context ([18e21ea](https://github.com/elct9620/kobako/commit/18e21eac8b160ade2724578aeacd86170403ee2c))
+* **ext:** trust the artifact disk cache only in an exclusively writable directory ([17679cc](https://github.com/elct9620/kobako/commit/17679cc0d38d2a1b605e2faaeed762477a718c18))
+
+
+### Performance Improvements
+
+* **bench:** re-bless the anchor onto the post-0.9.2 performance round ([195224d](https://github.com/elct9620/kobako/commit/195224d5d48e53dc2be17752e6d6af6382a0c1ec))
+* **catalog:** drop the alloc-path block iteration from the gadget refusal ([542fe59](https://github.com/elct9620/kobako/commit/542fe59464bde57283d8e91984b82e82592bc3ab))
+* **ext:** amortise module compilation across processes via .cwasm cache ([2e688bc](https://github.com/elct9620/kobako/commit/2e688bc4a1cdf1d0d4d5a0bce2efb314a5b8d1f7))
+* **ext:** bound and harden the compiled-artifact cache ([949f222](https://github.com/elct9620/kobako/commit/949f2227af7cdf7d1913dcae58df683912a7dbd5))
+* **ext:** cache ABI export handles and per-path InstancePre ([47573d0](https://github.com/elct9620/kobako/commit/47573d022233c788ce94413d1a2901ee9d62fc2e))
+* **lib:** cache sealed frame encodings and cut decode-walk allocations ([e599573](https://github.com/elct9620/kobako/commit/e599573e37531b363baca83a1aa5833930100320))
+
 ## [0.9.2](https://github.com/elct9620/kobako/compare/v0.9.1...v0.9.2) (2026-06-11)
 
 

data/README.md

@@ -69,7 +69,7 @@ The script executes inside the Wasm guest. It cannot read your filesystem, open
 
 ### Services
 
-Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior.md`](docs/behavior.md) B-07..B-12.
+Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior/registration.md`](docs/behavior/registration.md) B-07..B-12.
 
 ```ruby
 class User
@@ -93,7 +93,7 @@ Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the hos
 
 ### Output Capture
 
-Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior.md`](docs/behavior.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 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?`.
 
 ```ruby
 result = sandbox.eval(<<~RUBY)
@@ -134,7 +134,7 @@ end
 
 ### 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.md`](docs/behavior.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 [`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).
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
@@ -179,7 +179,8 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
    ──────────────── invocation N ───────────────────
 
-     1. allocate fresh mrb_state
+     1. start from the canonical boot state
+        (mruby pre-initialized into the artifact at build time)
 
      2. replay snippets (in insertion order):
           :Adder     → defines Adder
@@ -189,7 +190,7 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
      4. return value to host
 
-     5. discard mrb_state; reset per-invocation state:
+     5. discard the instance; reset per-invocation state:
           · Handles invalidated
           · stdout / stderr buffers cleared
           · memory delta zeroed
@@ -199,9 +200,30 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
 For workloads that must be isolated from each other (one Sandbox per tenant, per student submission, per agent session), construct a fresh `Kobako::Sandbox` per scope — wasmtime's Engine and the compiled Module are cached at process scope, so additional Sandboxes amortize cold-start cost automatically.
 
+### Pooling
+
+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 ~30 µ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).
+
+```ruby
+pool = Kobako::Pool.new(slots: 4) do |sandbox|
+  sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
+end
+
+pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))) }
+```
+
+| Option | Meaning | Default |
+|--------|---------|---------|
+| `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.
+
 ### Service Blocks
 
-A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
+A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior/yield.md`](docs/behavior/yield.md) B-23..B-30.
 
 ```ruby
 sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
@@ -212,7 +234,7 @@ sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
 
 ### Handle Management
 
-A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
+A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior/dispatch.md`](docs/behavior/dispatch.md) B-13..B-21, B-34, B-37).
 
 ```ruby
 class Greeter
@@ -248,7 +270,7 @@ This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and
 
 ### Snippets & Entrypoints
 
-`Sandbox#preload` registers named mruby snippets that replay against the fresh `mrb_state` before every invocation; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
+`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior/invocation.md`](docs/behavior/invocation.md) B-31..B-33).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -262,7 +284,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 ```
    per-invocation replay (every #eval / #run, snippets in insertion order):
 
-      fresh mrb_state
+      canonical boot state
             │
             ├──▶ replay :Adder            (defines Adder)
             │
@@ -271,7 +293,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
             └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
                        │
                        ▼
-                  return value, then mrb_state discarded
+                  return value, then instance discarded
 ```
 
 `#preload` accepts two payload forms:
@@ -300,6 +322,11 @@ sandbox.define(:Cfg).bind(:Settings, ThemeReader.new)  # not: bind(:Settings, Ap
 sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
 ```
 
+When a purpose-built wrapper is more than you need, an object can gate its own surface in
+place: a private `respond_to_guest?(name)` answers, per method, whether the guest may call
+it. Returning `false` for every name makes the object opaque — a credential the guest
+forwards to another Service but never reads — while a named subset becomes an allow-list.
+
 Guest code can name any `<Namespace>::<Member>` path, but a forged name only resolves to
 something you bound — the real authorization gate is this host-side allowlist. Give each
 trust context its own Sandbox, and see [`docs/security.md`](docs/security.md) for the rest
@@ -312,15 +339,16 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
-| First `Sandbox.new` in a fresh process (Engine + Module JIT) | ~600 ms one-time      |
-| Subsequent `Sandbox.new` (Engine cache warm)                 | ~125 µs               |
-| Warm `#eval("nil")` on a reused Sandbox                      | ~135 µs               |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~165 µs               |
-| Service call amortized inside one invocation                 | ~6.7 µs               |
-| Snippet replay per invocation                                | ~7-9 µs each          |
-| Per additional Sandbox (RSS)                                 | ~570 KB               |
-
-Construct one Sandbox at boot so the ~600 ms JIT cost lands off the request hot path. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 7-8k `#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.
+| First `Sandbox.new` ever for a Guest Binary (Module JIT, then disk-cached) | ~500 ms once per machine |
+| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~5 ms one-time        |
+| Subsequent `Sandbox.new` (caches warm)                       | ~30 µs                |
+| Warm `#eval("nil")` on a reused Sandbox                      | ~73 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~104 µs               |
+| Service call amortized inside one invocation                 | ~6.8 µs               |
+| Snippet replay per invocation                                | ~8 µ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 ~32 MB total. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 16k `#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.
 
 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 (`#10` 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.
 

data/lib/kobako/capture.rb

@@ -4,7 +4,7 @@ module Kobako
   # Host-side captured prefix of guest stdout / stderr produced during a
   # single +Kobako::Sandbox+ invocation, paired with the truncation flag
   # the WASI pipe sets when the guest wrote past the configured per-channel
-  # cap ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
+  # cap.
   #
   # Immutable value object: the captured bytes and the truncation flag
   # always travel together and the instance is frozen on construction.
@@ -30,14 +30,12 @@ module Kobako
     end
 
     # Returns +true+ iff the underlying capture channel exceeded its
-    # configured cap during the originating +Sandbox+ invocation
-    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
+    # configured cap during the originating +Sandbox+ invocation.
     def truncated? = @truncated
 
-    # Pre-invocation sentinel ({docs/behavior.md B-05}[link:../../docs/behavior.md]).
-    # Empty UTF-8 bytes and +truncated? == false+; reused by every fresh
-    # +Sandbox+ and by +Sandbox+ between invocations to denote "no capture
-    # yet".
+    # Pre-invocation sentinel. Empty UTF-8 bytes and +truncated? == false+;
+    # reused by every fresh +Sandbox+ and by +Sandbox+ between invocations
+    # to denote "no capture yet".
     EMPTY = new(bytes: "", truncated: false)
   end
 end

data/lib/kobako/catalog/handles.rb

@@ -5,41 +5,29 @@ require_relative "../handle"
 module Kobako
   module Catalog
     # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-    # The table is owned by +Kobako::Sandbox+
-    # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]) and injected
+    # The table is owned by +Kobako::Sandbox+ and injected
     # into the per-Sandbox +Kobako::Catalog::Namespaces+ so guest→host dispatch
     # resolves Handle targets and arguments against the same table that
-    # host→guest wire encoding allocates into
-    # ({docs/behavior.md B-14, B-34}[link:../../../docs/behavior.md]).
+    # host→guest wire encoding allocates into.
     #
-    # Lifecycle invariants ({docs/behavior.md}[link:../../../docs/behavior.md]):
+    # Lifecycle invariants:
     #
-    #   - {docs/behavior.md B-15}[link:../../../docs/behavior.md] — 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+.
+    #   - 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+.
     #
-    #   - {docs/behavior.md B-19}[link:../../../docs/behavior.md] — At every
-    #     invocation boundary (via +#reset!+), every Handle issued under the
-    #     old state becomes invalid. Reset applies uniformly regardless of
-    #     allocation source (B-14 Service return or B-34 host-injected
+    #   - At every invocation boundary (via +#reset!+), every Handle issued
+    #     under the old state becomes invalid. Reset applies uniformly
+    #     regardless of allocation source (Service return or host-injected
     #     argument).
     #
-    #   - {docs/behavior.md B-21}[link:../../../docs/behavior.md] — The cap is
-    #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises
-    #     immediately — no silent truncation, no wrap, no ID reuse.
+    #   - The cap is +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap
+    #     raises immediately — no silent truncation, no wrap, no ID reuse.
     class Handles
-      # Reflective gadget types that are never minted as a Capability Handle
-      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): wrapping a
-      # +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a callable
-      # proxy onto host reflection (a returned +Binding+ reaches +Binding#eval+).
-      UNWRAPPABLE_TYPES = [Binding, Method, UnboundMethod].freeze
-      private_constant :UNWRAPPABLE_TYPES
-
       # Build a fresh, empty table. +next_id+ is an internal seam that
-      # sets the starting value of the monotonic counter (defaults to 1 per
-      # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
+      # 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.
       def initialize(next_id: 1)
         @entries = {} # : Hash[Integer, untyped]
@@ -52,8 +40,7 @@ module Kobako
       # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
       # +Kobako::HandlerExhaustedError+ 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
-      # ({docs/behavior.md B-21}[link:../../../docs/behavior.md]).
+      # and the allocator share the same invariant.
       #
       # Returning a Handle (rather than a bare Integer id) keeps the
       # allocator's output a domain entity; +Kobako::Handle.restore+
@@ -76,9 +63,8 @@ module Kobako
         @entries[id]
       end
 
-      # Clear all entries AND reset the counter to 1. Called at the per-invocation
-      # boundary by +Kobako::Sandbox+ — see
-      # {docs/behavior.md B-19}[link:../../../docs/behavior.md]. Returns +self+.
+      # Clear all entries AND reset the counter to 1. Called at the
+      # per-invocation boundary by +Kobako::Sandbox+. Returns +self+.
       def reset!
         @entries.clear
         @next_id = 1
@@ -96,17 +82,20 @@ module Kobako
 
       private
 
-      # Refuse to mint a Capability Handle for a reflective gadget
-      # ({UNWRAPPABLE_TYPES}, B-43). Raising here keeps the rule at the single
-      # mint point, so it holds on both the Service-return (B-14) and the
-      # +#run+ host→guest auto-wrap (B-34) paths.
+      # Refuse to mint a Capability Handle for a reflective gadget:
+      # a +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a
+      # callable proxy onto host reflection (a returned +Binding+ reaches
+      # +Binding#eval+). 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)
-        return unless UNWRAPPABLE_TYPES.any? { |type| object.is_a?(type) }
-
-        raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        case object
+        when Binding, Method, UnboundMethod
+          raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        end
       end
 
-      # Guard {#alloc} against issuing an ID past the B-21 cap. Returns +nil+
+      # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
       # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID

data/lib/kobako/catalog/namespaces.rb

@@ -9,8 +9,7 @@ module Kobako
   module Catalog
     # Kobako::Catalog::Namespaces — per-Sandbox registry of
     # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
-    # and the preamble emitted on Frame 1
-    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]).
+    # and the preamble emitted on Frame 1.
     #
     # Public API:
     #
@@ -24,29 +23,27 @@ module Kobako
     # +Kobako::Transport::Dispatcher+'s responsibility — the Dispatcher
     # receives this registry and the +Catalog::Handles+ as arguments from
     # the +Runtime#on_dispatch+ Proc that +Kobako::Sandbox#initialize+
-    # installs ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
-    # The registry holds an injected +Catalog::Handles+ reference so
+    # installs. The registry holds an injected +Catalog::Handles+ reference so
     # dispatch target resolution and host→guest auto-wrap share the same
-    # Sandbox-owned allocator ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
+    # Sandbox-owned allocator.
     class Namespaces
       # Build a fresh registry. +handler+ is an internal seam that injects
       # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
-      # is pinned near +MAX_ID+ to exercise the B-21 cap-exhaustion path
+      # is pinned near +MAX_ID+ to exercise the cap-exhaustion path
       # without 2³¹ allocations. Production callers leave it at the default.
       def initialize(handler: Catalog::Handles.new)
         @namespaces = {} # : Hash[String, Kobako::Namespace]
         @handler = handler
         @sealed = false
+        @encoded = nil # : String?
       end
 
-      # Declare or retrieve the Namespace named +name+ (idempotent —
-      # {docs/behavior.md B-10}[link:../../../docs/behavior.md]).
+      # Declare or retrieve the Namespace named +name+ (idempotent).
       # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
       # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
       # name, creating it if it does not exist. Raises +ArgumentError+ when
       # +name+ is malformed, or when called after the owning Sandbox has been
-      # sealed by its first invocation
-      # ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
+      # sealed by its first invocation.
       def define(name)
         raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
 
@@ -73,21 +70,35 @@ module Kobako
         namespace.fetch(member_name)
       end
 
-      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
-      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Routes through
-      # {Kobako::Codec::Encoder} like every other host-side wire encode so
-      # there is a single codec path; the preamble carries only Strings and
-      # Arrays, so none of the kobako ext types actually fire. Structure:
-      # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
-      # +String+ of msgpack bytes.
+      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery.
+      # Routes through {Kobako::Codec::Encoder} like every other host-side
+      # wire encode so there is a single codec path; the preamble carries
+      # only Strings and Arrays, so none of the kobako ext types actually
+      # fire. Structure: +[["Namespace", ["MemberA", "MemberB"]], ...]+.
+      # Returns a binary +String+ of msgpack bytes.
+      #
+      # Once sealed, the bytes are computed once and reused for every
+      # subsequent invocation: sealing freezes Service registration at the
+      # first invocation, so the preamble is exactly the bindings that
+      # existed at that moment — a bind reaching a +Kobako::Namespace+
+      # after the seal raises +ArgumentError+ and never alters Frame 1.
       def encode
-        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+        return @encoded if @encoded
+
+        bytes = Codec::Encoder.encode(@namespaces.values.map(&:to_preamble)).freeze
+        @encoded = bytes if @sealed
+        bytes
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
-      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      # Mark the registry as sealed and propagate the seal to every
+      # declared +Kobako::Namespace+. Called by +Sandbox+ on the first
+      # invocation. After sealing, both #define and +Namespace#bind+
+      # raise ArgumentError. Idempotent.
       def seal!
+        return self if @sealed
+
         @sealed = true
+        @namespaces.each_value(&:seal!)
         self
       end
 

data/lib/kobako/catalog/snippets.rb

@@ -6,8 +6,7 @@ require_relative "../snippet"
 module Kobako
   module Catalog
     # Kobako::Catalog::Snippets — per-Sandbox insertion-ordered registry
-    # of preloaded snippets
-    # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
+    # of preloaded snippets.
     #
     # Entries replay against the fresh +mrb_state+ before per-invocation
     # source / entrypoint resolution. Each +Snippet::Source+ entry's +name+
@@ -15,22 +14,21 @@ module Kobako
     # +debug_info+ that surfaces in every backtrace frame originating from
     # the snippet as +(snippet:Name):line+. Duplicate names within the
     # +code:+ form would produce ambiguous attribution and are rejected at
-    # registration time
-    # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
+    # registration time.
     # +Snippet::Binary+ entries carry no host-side name — their canonical
     # name lives in the bytecode's +debug_info+ and is read by the guest at
     # load time; the host does not extract it.
     #
-    # Sealing (B-33) is governed by the owning Sandbox — the registry itself
+    # Sealing is governed by the owning Sandbox — the registry itself
     # is append-only and exposes no mutation API beyond +#register+; the
     # Sandbox guards +#register+ behind the seal check before delegating.
     class Snippets
-      # Ruby constant-name pattern enforced on snippet names
-      # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
+      # Ruby constant-name pattern enforced on snippet names.
       NAME_PATTERN = /\A[A-Z]\w*\z/
 
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @encoded = nil # : String?
       end
 
       # Serialize the registered snippets to wire bytes. Each entry
@@ -42,12 +40,17 @@ module Kobako
       # carriers — this collection-tier method reads their attributes
       # externally via +entry_payload+ rather than asking each entry to
       # self-encode.
+      #
+      # The bytes are memoized — the table is replayed verbatim on every
+      # invocation after sealing, so Frame 3 never changes between
+      # encodes; {#register} drops the memo while the table is still open.
       def encode
-        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
+        return @encoded if @encoded
+
+        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
       end
 
-      # Register one preloaded snippet in either of two forms
-      # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+      # Register one preloaded snippet in either of two forms.
       #
       #   * Source form +register(code: src, name: Name)+ — +src+ is the
       #     mruby source as a String; the bytes are re-encoded as UTF-8
@@ -58,16 +61,15 @@ module Kobako
       #     precompiled RITE bytecode as a String, duplicated and forced
       #     to ASCII-8BIT so msgpack-ruby ships it as +bin+. Returns
       #     +nil+ — bytecode entries are anonymous on the host side; any
-      #     structural validation
-      #     ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
-      #     is deferred to the guest at first replay.
+      #     structural validation is deferred to the guest at first replay.
       #
       # The two forms are mutually exclusive: shape validation lives
       # here so callers (chiefly +Kobako::Sandbox#preload+) collapse to
       # a single delegation. Raises +ArgumentError+ on mixed forms,
-      # missing keywords, wrong types, malformed +name+ (E-34), or
-      # duplicate +code:+ +name+ (E-33).
+      # missing keywords, wrong types, malformed +name+, or
+      # duplicate +code:+ +name+.
       def register(code: nil, name: nil, binary: nil)
+        @encoded = nil
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 
@@ -81,7 +83,7 @@ module Kobako
 
       # Source-form register path. Delegates argument-shape checks to
       # +ensure_source_args!+ (which returns the narrowed +[code, name]+
-      # pair), normalises +name+ to a Symbol, rejects duplicates (E-33),
+      # pair), normalises +name+ to a Symbol, rejects duplicates,
       # and appends the Source entry.
       def register_source!(code, name)
         code, name = ensure_source_args!(code, name)

data/lib/kobako/codec/decoder.rb

@@ -64,7 +64,11 @@ module Kobako
           case value
           when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
           when Array  then value.each { |v| validate_utf8!(v) }
-          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          when Hash
+            value.each do |key, val|
+              validate_utf8!(key)
+              validate_utf8!(val)
+            end
           end
         end
       end

data/lib/kobako/codec/utils.rb

@@ -19,8 +19,7 @@ module Kobako
     #   - Representability predicate ({representable?}) and the symmetric
     #     host→guest +#run+ argument walk ({deep_wrap}) used by
     #     +Kobako::Transport::Run#encode+ to route non-representable leaves
-    #     through the Sandbox's +Kobako::Catalog::Handles+
-    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
+    #     through the Sandbox's +Kobako::Catalog::Handles+.
     #
     # All helpers are pure — they only inspect inputs, never mutate
     # them — except {deep_wrap}, whose only side effect is allocating
@@ -84,8 +83,7 @@ module Kobako
 
       # Deep-walk Array / Hash containers in +value+ and replace every
       # leaf that fails {representable?} with a +Kobako::Handle+
-      # allocated from +handler+
-      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
+      # allocated from +handler+. The
       # walk only descends through representable container shapes
       # (Array, Hash) one structural level at a time; a non-representable
       # leaf is wrapped as-is without inspecting its internal structure.
@@ -116,8 +114,7 @@ module Kobako
 
       # Deep-walk Array / Hash containers in +value+ and replace every
       # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
-      # it to ({docs/behavior.md B-37}[link:../../../docs/behavior.md]).
-      # The symmetric inverse of {deep_wrap}: that walk allocates objects
+      # it to. The symmetric inverse of {deep_wrap}: that walk allocates objects
       # into Handles on the host→guest argument path; this walk resolves
       # Handles back to their objects on every guest→host value path — the
       # +#eval+ / +#run+ result and the yield-block result alike. The walk
@@ -126,11 +123,11 @@ module Kobako
       # unchanged.
       #
       # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
-      # +Kobako::Handle+, never a guest-forged one — B-20); +handler+ must
+      # +Kobako::Handle+, never a guest-forged one); +handler+ must
       # respond to +#fetch(id) -> object+ (a host-side
       # +Kobako::Catalog::Handles+). +handler.fetch+ raises
-      # +Kobako::SandboxError+ for an id with no live binding, which is the
-      # corrupted-runtime fallback B-37 specifies.
+      # +Kobako::SandboxError+ for an id with no live binding, the
+      # corrupted-runtime fallback.
       def deep_restore(value, handler)
         case value
         when ::Array then value.map { |element| Utils.deep_restore(element, handler) }