kobako 0.27.0 → 0.29.0

data/ROADMAP.md

@@ -1,25 +1,31 @@
 # Roadmap
 
-kobako is a Ruby gem providing an in-process Wasm sandbox for untrusted mruby
-code: a wasmtime host runs a precompiled `kobako.wasm` guest, with host↔guest
-Transport over a MessagePack wire. Features cover one-shot `#eval`, preload +
-`#run` dispatch, Service injection at constant-path names, opaque
-Capability Handles, block yield re-entry, three-class error attribution,
-output capture, and a warm Sandbox pool.
+kobako runs untrusted mruby code in an in-process Wasm sandbox. A wasmtime
+host drives a precompiled `kobako.wasm` guest over a MessagePack wire. Each
+row below links a feature to its scenarios and to where its code starts.
 
-| Feature | Entry Points | Notes |
-|---------|-------------|-------|
-| ✅ [F-01 Sandbox instantiation](docs/spec/behavior/sandbox.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | — |
-| ✅ [F-02 Service binding](docs/spec/behavior/services.md) | [lib/kobako/catalog/services.rb](lib/kobako/catalog/services.rb) | — |
-| ✅ [F-04 Synchronous mruby source execution (`#eval`)](docs/spec/behavior/sandbox.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | — |
-| ✅ [F-05 Guest-initiated Transport dispatch](docs/spec/behavior/transport-dispatch.md) | [lib/kobako/transport/dispatcher.rb](lib/kobako/transport/dispatcher.rb) | — |
-| ✅ [F-06 Capability Handle encoding and referencing](docs/spec/behavior/transport-dispatch.md) | [lib/kobako/catalog/handles.rb](lib/kobako/catalog/handles.rb) | — |
-| ✅ [F-07 Three-class error attribution and raising](docs/spec/behavior/outcome.md) | [lib/kobako/outcome.rb](lib/kobako/outcome.rb) | A guest-entry decode failure is exercised only through its payload half ([`CD-003`](docs/spec/behavior/codec.md)); a Run envelope that does not frame is not reachable through the public API |
-| ✅ [F-08 Guest output capture](docs/spec/behavior/sandbox.md) | [lib/kobako/capture.rb](lib/kobako/capture.rb) | — |
-| ✅ [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 (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/spec/behavior/transport-yield.md) | [lib/kobako/transport/yielder.rb](lib/kobako/transport/yielder.rb) | — |
-| ✅ [F-13 Snippet preloading (`#preload`)](docs/spec/behavior/sandbox.md) | [lib/kobako/catalog/snippets.rb](lib/kobako/catalog/snippets.rb) | — |
-| ✅ [F-14 Synchronous entrypoint dispatch (`#run`)](docs/spec/behavior/sandbox.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | — |
-| ✅ [F-15 Warm Sandbox pool checkout (`Kobako::Pool`)](docs/spec/behavior/pool.md) | [lib/kobako/pool.rb](lib/kobako/pool.rb) | — |
+| Feature | Entry Points |
+|---------|-------------|
+| ✅ [Sandbox](docs/spec/behavior/sandbox.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) |
+| ✅ [Service registration](docs/spec/behavior/services.md) | [lib/kobako/catalog/services.rb](lib/kobako/catalog/services.rb) |
+| ✅ [Runtime](docs/spec/behavior/runtime.md) | [lib/kobako/runtime.rb](lib/kobako/runtime.rb) |
+| ✅ [Pool](docs/spec/behavior/pool.md) | [lib/kobako/pool.rb](lib/kobako/pool.rb) |
+| ✅ [Extension](docs/spec/behavior/extension.md) | [lib/kobako/extension.rb](lib/kobako/extension.rb) |
+| ✅ [Outcome attribution](docs/spec/behavior/outcome.md) | [lib/kobako/outcome.rb](lib/kobako/outcome.rb) |
+| ✅ [Transport dispatch](docs/spec/behavior/transport-dispatch.md) | [lib/kobako/transport/dispatcher.rb](lib/kobako/transport/dispatcher.rb) |
+| ✅ [Yield re-entry](docs/spec/behavior/transport-yield.md) | [lib/kobako/transport/yielder.rb](lib/kobako/transport/yielder.rb) |
+| ✅ [Dispatch boundary](docs/spec/behavior/transport-boundary.md) | [lib/kobako/transport/exposure.rb](lib/kobako/transport/exposure.rb) |
+| ✅ [Payload encoding](docs/spec/behavior/payload-encoding.md) | [lib/kobako/payload/](lib/kobako/payload/) |
+| ✅ [Payload wire](docs/spec/behavior/codec.md) | [lib/kobako/codec/](lib/kobako/codec/) |
+| ✅ [Core envelope](docs/spec/behavior/envelope.md) | [crates/kobako-transport/](crates/kobako-transport/) |
+| ✅ [mruby guest](docs/spec/behavior/mruby.md) | [wasm/kobako-mruby/](wasm/kobako-mruby/) |
+| ✅ [Guest IO](docs/spec/behavior/io.md) | [wasm/kobako-io/](wasm/kobako-io/) |
+| ✅ [Guest JSON](docs/spec/behavior/json.md) | [wasm/kobako-json/](wasm/kobako-json/) |
+| ✅ [Regexp](docs/spec/behavior/regexp.md) | [wasm/kobako-regexp/src/regexp.rs](wasm/kobako-regexp/src/regexp.rs) |
+| ✅ [Regexp over String](docs/spec/behavior/regexp-string.md) | [wasm/kobako-regexp/src/string_ext.rs](wasm/kobako-regexp/src/string_ext.rs) |
+| ✅ [MatchData](docs/spec/behavior/regexp-matchdata.md) | [wasm/kobako-regexp/src/matchdata.rs](wasm/kobako-regexp/src/matchdata.rs) |
+| ✅ [Guest File](docs/spec/behavior/file.md) | [wasm/kobako-io/src/file.rs](wasm/kobako-io/src/file.rs) |
+| ✅ [Filesystem](docs/spec/behavior/filesystem.md) | [crates/kobako-runtime/src/filesystem.rs](crates/kobako-runtime/src/filesystem.rs) |
+| ✅ [Mount](docs/spec/behavior/mount.md) | [lib/kobako/catalog/mount.rb](lib/kobako/catalog/mount.rb) |
+| ✅ [Ruby Filesystem](docs/spec/behavior/ruby-filesystem.md) | [ext/kobako/src/runtime/filesystem/ruby.rs](ext/kobako/src/runtime/filesystem/ruby.rs) |
+| ✅ [Journeys](docs/spec/behavior/journeys.md) | [test/e2e/test_journeys.rb](test/e2e/test_journeys.rb) |

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
 
@@ -24,7 +24,7 @@ ask to stay anonymous.
 ## Scope
 
 In scope is anything that lets guest code cross the isolation boundary it should not:
-reaching host memory, the filesystem, the network, or `ENV`; obtaining ambient time or
+reaching host memory, the filesystem beyond what you mounted, the network, or `ENV`; obtaining ambient time or
 entropy the host froze; reaching a Service you never bound; or a
 memory-safety fault in the host codec or wasmtime driver.
 

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,122 @@
 # Changelog
 
+## [0.19.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.18.0...kobako-runtime-v0.19.0) (2026-10-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* **runtime:** a struct literal no longer builds OpenOptions, Metadata, DirEntry, Snapshot, Capture, or Usage outside kobako-runtime; use their `new` or `Default` and assign each field.
+* the Guest ABI is version 5, so a Guest Binary built against version 4 is refused at Sandbox construction until rebuilt. The Yielder trait of kobako-runtime gains frame and takes the frame in yield_to_block; the Guest trait of kobako-core and the MrbGuest trait of kobako-mruby take the frame in yield_to_block; Downcall::Yield carries frame and args.
+* **runtime:** the Runtime trait's invoke takes the invocation's Grants as a fourth argument, so every engine implementing it must accept them.
+
+### Features
+
+* check what a rename moves as it moves, refusing a directory beneath a Policy ([23794bf](https://github.com/elct9620/kobako/commit/23794bfcb54e148126e29873fa9b52d9e3de8d8c))
+* **runtime:** bound the files and directories a Memory or Temporary holds ([8d0be0a](https://github.com/elct9620/kobako/commit/8d0be0ab3dc8c11bcb96865b0bf1a0bbb8dd3b16))
+* **runtime:** bound what a Memory or Temporary holds, 64 MiB by default ([2557d1b](https://github.com/elct9620/kobako/commit/2557d1ba7530aacfddf908aeddac561c4fbc5c8a))
+* **runtime:** draw every device a host does not name from one source ([210d55b](https://github.com/elct9620/kobako/commit/210d55b1b4e0699dc5ef56b4b6930be01658a3c6))
+* **runtime:** hand each invocation its Grants and let an engine declare the kinds it supports ([cba90ee](https://github.com/elct9620/kobako/commit/cba90eed09c8afcb23080cef1c9cbb3650648472)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** keep a directory descriptor's identity its own while open ([6267642](https://github.com/elct9620/kobako/commit/6267642ea831917be76a0101e8d206ccfa8834c1))
+* **runtime:** let a dispatch handler abandon its invocation ([179da9e](https://github.com/elct9620/kobako/commit/179da9ee1f31fed9e6d0c149faee0ad55f8db487))
+* **runtime:** let a Filesystem's file refuse its close ([af16007](https://github.com/elct9620/kobako/commit/af1600797b098796dd6f329672c7d04e2e1cd2fa)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** let a Mount decide its own access as the one kind of Grant ([5c9189e](https://github.com/elct9620/kobako/commit/5c9189eea8ac61cf165dca1b38e459c4f14acdd0)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** let a Mount's Policy judge the spelling the host stores ([5281057](https://github.com/elct9620/kobako/commit/52810573f22d2a3edfae9b34b7767a5f440fba15))
+* **runtime:** let the records a Filesystem or an engine builds gain fields ([c0ef88d](https://github.com/elct9620/kobako/commit/c0ef88d0b6df16d651e4c49226e41667307d772f))
+* **runtime:** name a file grown past what a Filesystem keeps ([7bac3e6](https://github.com/elct9620/kobako/commit/7bac3e65534097b85d93f5967b6c73a979869a78))
+* **runtime:** name each code a Filesystem may fail with ([1d980fa](https://github.com/elct9620/kobako/commit/1d980fa4328bad42e8a8665adfec9fc844690e97))
+* **runtime:** name the POSIX error each FilesystemError stands for ([01c301b](https://github.com/elct9620/kobako/commit/01c301b4af9f489594eb7a98ab48c508e5b61ca4))
+* **runtime:** refuse a Memory seed path through `..` ([b31434d](https://github.com/elct9620/kobako/commit/b31434d386ebde838c15755619c67da95311ecf6))
+* **runtime:** refuse a Mount at a path that is no absolute guest path ([a525758](https://github.com/elct9620/kobako/commit/a5257589f9d831b9a3b6d1952df6e5c8469630e1))
+* **runtime:** report a link a lookup does not follow as a link ([8c1e0b3](https://github.com/elct9620/kobako/commit/8c1e0b3e63fbc91b10f11cd91817ce94de24c7e6))
+* **runtime:** report the identity of what a path holds ([392bc0e](https://github.com/elct9620/kobako/commit/392bc0e9f2fb935934a0031bf7d64dec0b27df6a))
+* **runtime:** say whether a path beneath a Mount may pass a link ([7706a25](https://github.com/elct9620/kobako/commit/7706a2537bf8e5975b2b227bef0c05cb48c09f4b))
+* **runtime:** seed a Memory from a list that may not hold, answering why ([8ac2dfd](https://github.com/elct9620/kobako/commit/8ac2dfdf73b84fe2e53405a653d861ddca9ea98c))
+* **runtime:** ship the Memory, Temporary, Directory, and Overlay filesystems ([c60c453](https://github.com/elct9620/kobako/commit/c60c4535e966ffd501e03d7be7fef0a44d860b0b)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** stack an Overlay from Layers, each read-only or writable ([6c88188](https://github.com/elct9620/kobako/commit/6c88188cd7992c218f8c5a3be30981e685804078)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+
+
+### Bug Fixes
+
+* append through a Filesystem's file only in one step ([0509ca7](https://github.com/elct9620/kobako/commit/0509ca70d2d5a832303973ba0f7280be0731fd3d))
+* ask a mount's block once for a read ([f89bd16](https://github.com/elct9620/kobako/commit/f89bd16c1a71ed1d385ab9d3ac5974ac3f0a9103))
+* follow no link swapped in after a Policy judges a path ([ed93213](https://github.com/elct9620/kobako/commit/ed9321303dd45e113fc413e99e1240118cc4bbe4))
+* hold an Overlay's lock across each call, waiting without the GVL ([b8e7342](https://github.com/elct9620/kobako/commit/b8e734273fdc577a40be97c43c46d9548d66c625))
+* keep a link within the directory a descriptor opened ([952dd05](https://github.com/elct9620/kobako/commit/952dd0556969683f44798da94f9fc7a17c1f6d55))
+* run a stored block as the block of the Call that carried it ([bf33dc1](https://github.com/elct9620/kobako/commit/bf33dc1fd40c83498c6c12b0be52b3a835a144cf))
+* **runtime:** answer a host failure as the error naming it ([effd43a](https://github.com/elct9620/kobako/commit/effd43a85a3ba69aaa068d2c384c3b5cb466161c))
+* **runtime:** append to a Directory file in one host write ([4a5450a](https://github.com/elct9620/kobako/commit/4a5450a67e202e45299175c4fe7528cf50489f0e))
+* **runtime:** copy a file up whole when its Layer writes in parts ([89d87f7](https://github.com/elct9620/kobako/commit/89d87f7225611786467968ec34eba5a8223b5fc5))
+* **runtime:** fail an Overlay call a Layer cannot answer instead of guessing ([5ba0db3](https://github.com/elct9620/kobako/commit/5ba0db33c56ed837401bcb62345f81b4b50c317a))
+* **runtime:** hold each Memory entry under its own name ([8f1ba8a](https://github.com/elct9620/kobako/commit/8f1ba8a50d3d8ca3a695115d51b605be1f18e29e))
+* **runtime:** judge a link an Overlay's Layer holds as the link itself ([959c1f3](https://github.com/elct9620/kobako/commit/959c1f3dab6f6948baabbd914bbb86dfff090f7b))
+* **runtime:** keep an Overlay rename to one Layer and answer a landed change as done ([e3405b7](https://github.com/elct9620/kobako/commit/e3405b7139809ada202ffdb0d6bf1eef3dcbf056))
+* **runtime:** leave a Memory file as it was on a write of no bytes ([9f8fd23](https://github.com/elct9620/kobako/commit/9f8fd237b9b0042590b149f9b2051e0773d8b9af))
+* **runtime:** leave an Overlay unchanged when a removal or rename is refused ([a7bee4b](https://github.com/elct9620/kobako/commit/a7bee4b2a465a0ef0ad2e376c281dca82a0df0e1))
+* **runtime:** let a file or link in a Layer hide what lies below it ([fd579f6](https://github.com/elct9620/kobako/commit/fd579f679cfa8a83ec7d139066bc1a4570af398b))
+* **runtime:** make every Filesystem answer the methods that keep a guarantee ([00f5af6](https://github.com/elct9620/kobako/commit/00f5af63f34ac7722249746d0b0eb566da618803))
+* **runtime:** move a directory made again as the writable Layer's own ([ac3e864](https://github.com/elct9620/kobako/commit/ac3e864bbb0ce5d61def45e0403239be405481d3))
+* **runtime:** move a directory onto one that holds only markers ([934f0c3](https://github.com/elct9620/kobako/commit/934f0c39e0ad1189bdb1cb0461671245dea32f93))
+* **runtime:** open a Directory file the runtime neither reads nor writes ([6b30858](https://github.com/elct9620/kobako/commit/6b308583383d6803894b2c7af1a9ef05d72b0e7d)), closes [#78](https://github.com/elct9620/kobako/issues/78)
+* **runtime:** open a file already there without writing to create it ([7f76a1a](https://github.com/elct9620/kobako/commit/7f76a1af575739ae16c5daeb1df8268af44cea63))
+* **runtime:** panic on files a Memory cannot be seeded with ([cf5c835](https://github.com/elct9620/kobako/commit/cf5c835d7df8bf82972487280c6a6c79be955a68))
+* **runtime:** put an Overlay's markers back when the change fails ([78ddeed](https://github.com/elct9620/kobako/commit/78ddeeddda8b9f797a80ec3796b28e04cf99ffc9))
+* **runtime:** refuse a backslash in a Directory path on Windows ([88b5719](https://github.com/elct9620/kobako/commit/88b57195325b168395248a82b94a5ebf7e5f4142))
+* **runtime:** refuse a Directory append on Windows rather than take two steps ([a528cc9](https://github.com/elct9620/kobako/commit/a528cc9577f1b2e1359699e2400be93c1f3a9be7))
+* **runtime:** refuse a file moved beneath itself as no directory ([bfabb52](https://github.com/elct9620/kobako/commit/bfabb52b27080ee9e5000bd5524ea201a7e33d80))
+* **runtime:** refuse a host name that is not UTF-8 as an illegal sequence ([c4ff030](https://github.com/elct9620/kobako/commit/c4ff030ffa8e29fa1b10df4aaf6af65162c76353))
+* **runtime:** refuse a Memory file grown past what can be allocated ([302e2d4](https://github.com/elct9620/kobako/commit/302e2d4fcd5b31fee4e953e8993bb47d9a2a673a))
+* **runtime:** refuse an Overlay change landing beneath a read-only Layer ([e7b2f19](https://github.com/elct9620/kobako/commit/e7b2f19156df9773f669cbe8a7aaefc17591cca3))
+* **runtime:** refuse to open a FIFO, socket, or device beneath a Directory ([bdcaf78](https://github.com/elct9620/kobako/commit/bdcaf78bf131998648c65ac51ced4a588a79211f))
+* **runtime:** remove no directory as a file on any host ([c9c0820](https://github.com/elct9620/kobako/commit/c9c0820fd39c0744b9d9c367b977f6587d1f9589))
+* **runtime:** rename and copy up through an Overlay as overlayfs does ([ada5a86](https://github.com/elct9620/kobako/commit/ada5a86a8647d89666e9de808eb13ba638882e51))
+* **runtime:** replace neither a FIFO nor a directory with the other through an Overlay ([8fed062](https://github.com/elct9620/kobako/commit/8fed062438e105c6a784bf4bde1582fda9e3c9c2))
+* **runtime:** report a merged directory's identity alike through an Overlay's lstat ([ded3b4a](https://github.com/elct9620/kobako/commit/ded3b4aba78efa678318c38b139b5c9c76b5d3fd))
+* **runtime:** require cap-std 4.0.3 for the trailing-slash lookup fix ([549cfe0](https://github.com/elct9620/kobako/commit/549cfe07fc8b9affdc8a1765a9e4bc5963ef546e))
+* **runtime:** reserve an Overlay's marker name in any case ([ef39923](https://github.com/elct9620/kobako/commit/ef399230eabe01ad6eed632b2753880ae1fc322c))
+* **runtime:** reserve exactly what a Memory file grows by ([96f8141](https://github.com/elct9620/kobako/commit/96f8141442cac2170a8bf8a76055d4f4659b1100))
+* **runtime:** spell a Directory path's last name without following a link there ([c5e5ae7](https://github.com/elct9620/kobako/commit/c5e5ae74ec1f6ee07e24da08d7b097fb6a882961))
+* **runtime:** spell a path on XFS by listing rather than trusting exact names ([f89495d](https://github.com/elct9620/kobako/commit/f89495dcfd7c6d05d46ebc5dbae0039856cc15c6))
+* **wasmtime:** hold the whole invocation to its deadline ([231e325](https://github.com/elct9620/kobako/commit/231e32592699008adf3105050bee8b5528ea27a8))
+* **wasmtime:** place an append at the end as the file stands when it lands ([d7291c4](https://github.com/elct9620/kobako/commit/d7291c4f32fb1f5f2494c69c76796476bbcf4d43))
+* **wasmtime:** refuse a link an open asks not to follow ([123a01b](https://github.com/elct9620/kobako/commit/123a01b01f59cc69c0e3a23f9aeb01aa89132c07))
+
+
+### Performance Improvements
+
+* **runtime:** list an Overlay directory in time linear to its entries ([be3f446](https://github.com/elct9620/kobako/commit/be3f446f782cbd72b114f7b6072e3b50c391f093))
+* **runtime:** stop an Overlay's marker lookup at a directory a Layer lacks ([494fa09](https://github.com/elct9620/kobako/commit/494fa090e90806c50e4e8baaa4f1001efc388b45))
+
+## [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)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -2,10 +2,12 @@
 #
 # The contract a wasm engine must satisfy to drive a kobako guest,
 # free of any engine or frontend type: the `Runtime` trait plus the
-# neutral value types (`Snapshot`, `Trap`, `SetupError`, ...) and the
-# dispatch / yield re-entry traits a frontend supplies. Engine
-# implementations (`kobako-wasmtime`) and host frontends (the Ruby
-# ext) meet on this surface, so the engine stays swappable.
+# neutral value types (`Snapshot`, `Trap`, `SetupError`, ...), the
+# dispatch / yield re-entry traits a frontend supplies, and the Grants
+# a frontend hands each invocation, the Mount and the Filesystems it
+# places. Engine implementations (`kobako-wasmtime`) and host frontends
+# (the Ruby ext) meet on this surface, so the engine stays swappable.
+# `cap-std` confines the Directory Filesystem to its host directory.
 #
 # Self-contained by design: the Ruby gem ships this crate without the
 # `crates/` workspace manifest, so no `workspace = true` inheritance
@@ -13,7 +15,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.17.0"
+version = "0.19.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -27,4 +29,23 @@ categories = ["wasm", "virtualization"]
 # in-tree builds (and the Ruby gem, which ships both crates) resolving
 # locally.
 [dependencies]
-kobako-transport = { version = "0.17.0", path = "../kobako-transport" }
+kobako-transport = { version = "0.19.0", path = "../kobako-transport" }
+# cap-std resolves every path of the Directory Filesystem beneath its host
+# directory, refusing a `..` or a symbolic link that would lead out of it.
+# 4.0.3 is the first release whose trailing-slash lookup keeps that
+# refusal (GHSA-hp8f-xmx4-4qrg).
+cap-std = "4.0.3"
+# cap-fs-ext opens a Directory's path one directory at a time without
+# following a link, so a Mount's Policy judges the path its call reaches.
+cap-fs-ext = "4.0.3"
+
+# rustix switches a Directory file to append mode for one write, so the
+# host places it at the file's end in one step; std cannot set file flags.
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1.1.4", features = ["fs"] }
+
+# libc asks macOS for the name a directory stores, which a Mount's Policy
+# judges in place of a spelling the host folds; rustix has no
+# getattrlist.
+[target.'cfg(target_os = "macos")'.dependencies]
+libc = "0.2.191"

data/crates/kobako-runtime/README.md

@@ -4,28 +4,34 @@ Engine-neutral host runtime contract for
 [kobako](https://github.com/elct9620/kobako), an in-process Wasm
 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.
+A kobako host drives a Guest Binary through a wasm engine. This crate
+is where the two meet, free of any engine or frontend 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` | 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) |
+| `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 |
+| `grant` | the `Grant` a frontend hands each invocation, and the `GrantKind`s a runtime supports |
+| `mount` | the `Mount` at a guest path, and the `Policy` judging its paths |
+| `filesystem` | the `Filesystem` trait, its `Access`, and the four kinds kobako ships |
 | `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)
-map the neutral types onto their own language surface.
+Engine implementations such as `kobako-wasmtime` implement `Runtime`.
+Host frontends such as the kobako Ruby gem's native ext map the neutral
+types onto their own language surface.
 
 ## Usage
 
+Add the crate to an engine or a frontend that speaks the contract.
+
 ```toml
 [dependencies]
-kobako-runtime = "0.17.0" # x-release-please-version
+kobako-runtime = "0.19.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-runtime/src/dispatch.rs

@@ -25,4 +25,12 @@ use kobako_transport::envelope::{Call, Reply};
 /// the payload onward without copying it first.
 pub trait DispatchHandler: Send + Sync {
     fn dispatch(&self, call: Call<'_>, yielder: &mut dyn Yielder) -> Option<Reply>;
+
+    /// Whether the host gave up on this invocation, as when one of its
+    /// callbacks raised something meant for the host rather than the
+    /// guest. The engine ends the invocation at the next host call it
+    /// answers, so the guest cannot go on as if it had been answered.
+    fn abandoned(&self) -> bool {
+        false
+    }
 }

data/crates/kobako-runtime/src/error.rs

@@ -1,9 +1,9 @@
-//! Engine-neutral host error channels, free of any frontend dependency.
+//! Engine-neutral host error types, free of any frontend dependency.
 //!
 //! The run path produces these instead of constructing host-language
 //! exceptions directly; each frontend's boundary is the single place that
 //! maps them onto its own error classes (the Ruby ext does so in its error
-//! mapper). Keeping the channels frontend-free lets any engine
+//! mapper). Keeping the types frontend-free lets any engine
 //! implementation produce them unchanged.
 
 use std::fmt;
@@ -26,11 +26,10 @@ pub enum Trap {
 }
 
 /// A failure that yields no invocation outcome. The discriminant records
-/// the runtime's state so a frontend can attribute the failure per SPEC:
+/// the runtime's state so a frontend can attribute the failure:
 /// `ModuleNotBuilt` (the guest artifact is absent), `Dead` (the runtime
 /// could not be constructed), and `Intact` (the runtime is live but a
-/// host-side pre-call step failed, so no discard-and-recreate recovery is
-/// owed).
+/// host-side pre-call step failed before the engine ran).
 ///
 /// Non-exhaustive, as `Trap`: a frontend maps each state onto its own
 /// class, and a later state must not break that match.
@@ -45,14 +44,14 @@ pub enum SetupError {
 /// A failure that prevented the invocation from starting — a pre-call
 /// engine fault (`Trap`) or a host-side setup fault (`Setup`) — unified so
 /// the run mechanics can propagate both with `?`; a frontend destructures
-/// it back into the two channels. Faults after the guest export starts
+/// it back into the two. Faults after the guest export starts
 /// ride in `Completion::Trap` instead, so captures and usage survive them.
 ///
 /// Named for where it comes from — the `Err` of `Runtime::invoke` — so a
 /// host that also has its own `Error` in scope can hold both.
 ///
-/// Non-exhaustive, as its two channels are: a later way an invocation can
-/// fail to start must not break the frontends already destructuring it.
+/// Non-exhaustive: a later way an invocation can fail to start must not
+/// break the frontends already destructuring it.
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum InvokeError {
@@ -96,7 +95,7 @@ impl fmt::Display for SetupError {
     }
 }
 
-// Both channels sit on the seam a third-party engine implements against,
+// Both types sit on the seam a third-party engine implements against,
 // where a caller wants to lift them into `Box<dyn Error>` or `anyhow` with
 // `?`. `Trap` carries no source of its own, so neither reports one.
 impl std::error::Error for SetupError {}

data/crates/kobako-runtime/src/filesystem/directory/spelling.rs

@@ -0,0 +1,194 @@
+//! How a host directory spells a name it holds. A host that folds case or
+//! Unicode form reaches one entry by many names, so a Policy judging the
+//! name as asked would see a spelling the host never stored.
+//!
+//! macOS answers the stored name for any spelling. Elsewhere a listing
+//! finds the entry by its inode, skipped on a Linux filesystem known to
+//! match names exactly; without an inode, a spelling the listing lacks is
+//! refused.
+
+use std::io;
+
+use cap_std::fs::Dir;
+
+/// The name `parent` stores for the entry `name` reaches, a link reached
+/// as itself, or `None` when nothing is there.
+pub(super) fn stored_name(parent: &Dir, name: &str) -> io::Result<Option<String>> {
+    #[cfg(target_os = "macos")]
+    {
+        macos::stored_name(parent, name)
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        #[cfg(target_os = "linux")]
+        if linux::matches_exactly(parent) {
+            return match parent.symlink_metadata(name) {
+                Ok(_) => Ok(Some(name.to_string())),
+                Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(None),
+                Err(err) => Err(err),
+            };
+        }
+        stored_name_by_listing(parent, name)
+    }
+}
+
+/// The name a listing of `parent` holds for `name`: itself when listed,
+/// else the entry sharing its inode.
+#[cfg(not(target_os = "macos"))]
+fn stored_name_by_listing(parent: &Dir, name: &str) -> io::Result<Option<String>> {
+    let found = match parent.symlink_metadata(name) {
+        Ok(found) => found,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => return Err(err),
+    };
+    let mut names = Vec::new();
+    for entry in parent.entries()? {
+        let entry = entry?;
+        if entry.file_name() == name {
+            return Ok(Some(name.to_string()));
+        }
+        names.push(entry);
+    }
+    #[cfg(unix)]
+    {
+        use cap_std::fs::MetadataExt;
+        use std::os::unix::fs::DirEntryExt;
+        for entry in names {
+            if entry.ino() == found.ino() {
+                return entry
+                    .file_name()
+                    .into_string()
+                    .map(Some)
+                    .map_err(|_| io::ErrorKind::InvalidData.into());
+            }
+        }
+    }
+    #[cfg(not(unix))]
+    let _ = (found, names);
+    Err(io::ErrorKind::PermissionDenied.into())
+}
+
+#[cfg(target_os = "macos")]
+mod macos {
+    use std::ffi::CString;
+    use std::io;
+    use std::os::fd::AsRawFd;
+
+    use cap_std::fs::Dir;
+
+    /// The reply `getattrlist(2)` writes for `ATTR_CMN_NAME`: its length,
+    /// then a reference to the name stored behind it.
+    #[repr(C, packed(4))]
+    struct NameReply {
+        length: u32,
+        name: libc::attrreference_t,
+        data: [u8; 1024],
+    }
+
+    pub(super) fn stored_name(parent: &Dir, name: &str) -> io::Result<Option<String>> {
+        let path = CString::new(name).map_err(|_| io::Error::from(io::ErrorKind::InvalidInput))?;
+        let mut request = libc::attrlist {
+            bitmapcount: libc::ATTR_BIT_MAP_COUNT,
+            reserved: 0,
+            commonattr: libc::ATTR_CMN_NAME,
+            volattr: 0,
+            dirattr: 0,
+            fileattr: 0,
+            forkattr: 0,
+        };
+        let mut reply = NameReply {
+            length: 0,
+            name: libc::attrreference_t {
+                attr_dataoffset: 0,
+                attr_length: 0,
+            },
+            data: [0; 1024],
+        };
+        // SAFETY: every pointer names a live, correctly sized buffer, and
+        // the reply buffer's size bounds what the call writes.
+        let answered = unsafe {
+            libc::getattrlistat(
+                parent.as_raw_fd(),
+                path.as_ptr(),
+                (&raw mut request).cast(),
+                (&raw mut reply).cast(),
+                size_of::<NameReply>(),
+                libc::FSOPT_NOFOLLOW as libc::c_ulong,
+            )
+        };
+        if answered != 0 {
+            let err = io::Error::last_os_error();
+            return match err.kind() {
+                io::ErrorKind::NotFound => Ok(None),
+                _ => Err(err),
+            };
+        }
+        // The reference counts from itself, and `data` follows it; the
+        // length counts the terminating NUL.
+        let start = usize::try_from(reply.name.attr_dataoffset)
+            .ok()
+            .and_then(|offset| offset.checked_sub(size_of::<libc::attrreference_t>()));
+        let len = (reply.name.attr_length as usize).checked_sub(1);
+        let stored = start
+            .zip(len)
+            .and_then(|(start, len)| reply.data.get(start..start.checked_add(len)?))
+            .ok_or(io::ErrorKind::InvalidData)?;
+        String::from_utf8(stored.to_vec())
+            .map(Some)
+            .map_err(|_| io::ErrorKind::InvalidData.into())
+    }
+}
+
+#[cfg(target_os = "linux")]
+mod linux {
+    use cap_std::fs::Dir;
+    use rustix::fs::{fstatfs, ioctl_getflags};
+
+    /// The 32-bit magic numbers of filesystems matching names byte for
+    /// byte unless a directory is marked to fold case: ext4, Btrfs, tmpfs,
+    /// overlayfs, and F2FS. XFS is left to the listing, as a volume made
+    /// ASCII case-insensitive marks no directory.
+    const EXACT: [u32; 5] = [0xEF53, 0x9123_683E, 0x0102_1994, 0x794C_7630, 0xF2F5_2010];
+
+    /// The inode flag marking a directory whose names fold case, from
+    /// Linux's `FS_CASEFOLD_FL`.
+    const CASEFOLD: u32 = 0x4000_0000;
+
+    pub(super) fn matches_exactly(parent: &Dir) -> bool {
+        let exact = fstatfs(parent).is_ok_and(|stats| EXACT.contains(&(stats.f_type as u32)));
+        exact && ioctl_getflags(parent).is_ok_and(|flags| flags.bits() & CASEFOLD == 0)
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use cap_std::ambient_authority;
+
+        use super::super::stored_name_by_listing;
+        use super::Dir;
+
+        // A Linux host whose filesystem is not known to match exactly,
+        // XFS among them, spells by listing; the host here matches
+        // exactly, so the listing must answer as the lookup would.
+        // @behavior FS-081
+        #[test]
+        fn a_listing_spells_names_it_matches_exactly_as_given() {
+            let path = std::env::temp_dir().join(format!("kobako-listed-{}", std::process::id()));
+            let _ = std::fs::remove_dir_all(&path);
+            std::fs::create_dir_all(&path).expect("the host directory must be created");
+            std::fs::write(path.join("file"), "x").expect("the host file must be written");
+            let dir = Dir::open_ambient_dir(&path, ambient_authority())
+                .expect("the host directory must open");
+            let answers = (
+                stored_name_by_listing(&dir, "file").ok(),
+                stored_name_by_listing(&dir, "missing").ok(),
+            );
+            let _ = std::fs::remove_dir_all(&path);
+            assert_eq!(
+                answers,
+                (Some(Some("file".to_string())), Some(None)),
+                "a name the host holds, spelled by listing its directory, must come back as \
+                 given, and a name it lacks as none"
+            );
+        }
+    }
+}