kobako 0.27.0 → 0.28.0

data/crates/kobako-runtime/CHANGELOG.md

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

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.17.0"
+version = "0.18.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -27,4 +27,4 @@ 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.18.0", path = "../kobako-transport" }

data/crates/kobako-runtime/README.md

@@ -11,8 +11,9 @@ 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 |
 | `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
@@ -23,7 +24,7 @@ map the neutral types onto their own language surface.
 
 ```toml
 [dependencies]
-kobako-runtime = "0.17.0" # x-release-please-version
+kobako-runtime = "0.18.0" # x-release-please-version
 ```
 
 ## License

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/lib.rs

@@ -24,6 +24,6 @@ pub mod yielder;
 pub use dispatch::DispatchHandler;
 pub use error::{InvokeError, SetupError, Trap};
 pub use profile::Profile;
-pub use runtime::{Entry, Frames, Runtime};
+pub use runtime::{Entry, Runtime};
 pub use snapshot::{Capture, Completion, Snapshot, Usage};
 pub use yielder::Yielder;

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

@@ -11,7 +11,7 @@
 /// `Hermetic` is the full ambient-denial posture: ambient time and
 /// entropy denied at the WASI boundary, no filesystem / environment /
 /// network reachability, and no host import beyond the wire ABI's
-/// `__kobako_dispatch`. `Permissive` differs in exactly one grant —
+/// `__kobako_upcall`. `Permissive` differs in exactly one grant —
 /// live ambient time and entropy at the WASI boundary. Ordering
 /// follows strength (`Permissive < Hermetic`), so a floor check is a
 /// plain comparison.

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

@@ -1,7 +1,7 @@
 //! Engine-neutral host runtime contract.
 //!
 //! The contract a wasm engine must satisfy to drive a kobako guest: take a
-//! per-invocation entry plus its stdin frames, run one invocation on a
+//! per-invocation entry plus its Preamble, run one invocation on a
 //! fresh instance, and return the observable `Snapshot` — `Ok` iff the
 //! guest export ran, `Err` when the invocation never started. Nothing here
 //! mentions `magnus` or a Ruby type — a frontend supplies the dispatch
@@ -9,29 +9,31 @@
 
 use std::sync::Arc;
 
+use kobako_transport::envelope::Preamble;
+
 use crate::dispatch::DispatchHandler;
 use crate::error::InvokeError;
 use crate::profile::Profile;
 use crate::snapshot::Snapshot;
 
 /// The per-invocation entry: a one-shot mruby source (`Eval`) or an
-/// entrypoint-dispatch envelope (`Run`). Both ride alongside the stdin
-/// `Frames`; `Run` additionally copies its envelope into guest memory.
+/// entrypoint and its payload (`Run`). Both ride alongside the Sandbox's
+/// `Preamble`; the runtime frames `Run` and the `Preamble` onto the wire,
+/// so a frontend never encodes either. The payload is owned so that framing it needs no
+/// second copy.
 ///
-/// Closed rather than `#[non_exhaustive]`: the arms are the ABI's
-/// invocation exports, so the set only grows with an ABI version, and a
-/// runtime that has not implemented the new export should fail to
-/// compile rather than fall into a wildcard.
+/// Closed rather than `#[non_exhaustive]`: each arm is an invocation the
+/// downcall carries under its own tag, and a runtime that has not
+/// learned a new one should fail to compile rather than fall into a
+/// wildcard.
 pub enum Entry<'a> {
-    Eval { source: &'a [u8] },
-    Run { envelope: &'a [u8] },
-}
-
-/// The stdin frames shared by both entries: the Frame 1 preamble (the
-/// Sandbox's registrations) and the Frame 3 snippet-replay payload.
-pub struct Frames<'a> {
-    pub preamble: &'a [u8],
-    pub snippets: &'a [u8],
+    Eval {
+        source: &'a [u8],
+    },
+    Run {
+        entrypoint: &'a str,
+        payload: Vec<u8>,
+    },
 }
 
 /// Engine-neutral runtime: drives one guest invocation on a fresh instance
@@ -50,7 +52,7 @@ pub trait Runtime {
     fn invoke(
         &self,
         entry: Entry<'_>,
-        frames: Frames<'_>,
+        preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
     ) -> Result<Snapshot, InvokeError>;
 
@@ -59,4 +61,16 @@ pub trait Runtime {
     /// and a frontend refuses construction when the declaration falls
     /// below the floor its host application requested.
     fn profile(&self) -> Profile;
+
+    /// The bytecode of the Preamble's source Snippets, one per snippet in
+    /// order, compiled on a fresh instance that runs none of them. A
+    /// frontend hands over the Preamble an invocation sends and replays the
+    /// answer in its place, so every invocation after skips the compiler.
+    /// `None` whenever there is nothing to replay, an answer that would
+    /// carry that Preamble past the payload cap included: the frontend
+    /// keeps the source. The default compiles nothing, so an engine that
+    /// does not offer it still serves every invocation.
+    fn compile(&self, _preamble: &Preamble) -> Option<Vec<Vec<u8>>> {
+        None
+    }
 }

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

@@ -4,13 +4,14 @@
 //! frontend type and uniform across success and trap: how the invocation
 //! completed, the two captured output channels, and the resource usage.
 //! A `Snapshot` exists iff the guest export ran — a failure to even start
-//! the invocation travels on the `invoke` `Err` channel instead.
+//! the invocation comes back as the `Err` of `invoke` instead.
 //!
 //! `Usage` and `Capture` are shared with the tier above rather than
 //! translated at its boundary: what they carry is already frontend-free,
 //! so the Rust host SDK re-exports these types themselves.
 
 use crate::error::Trap;
+use kobako_transport::envelope::Outcome;
 
 /// One captured output channel: the bytes the guest wrote (already clipped
 /// to the channel's cap) and whether the cap was reached. `Default` is the
@@ -22,17 +23,19 @@ pub struct Capture {
     pub truncated: bool,
 }
 
-/// How the guest invocation completed: `Outcome` carries the encoded
-/// Outcome envelope, still undecoded; `Trap` is an engine fault after the
-/// export call started, kept as a value so the rest of the `Snapshot`
-/// survives it.
+/// How the guest invocation completed: `Outcome` is the result the guest
+/// left, already framed; `Trap` is an engine fault after the export call
+/// started, kept as a value so the rest of the `Snapshot` survives it.
 ///
-/// Closed rather than `#[non_exhaustive]`: an invocation either produced
-/// its final message or the engine stopped it, and there is no third way
-/// for one to end. A wildcard would only hide a frontend that had not
-/// been told otherwise.
+/// A guest that returned without an Outcome the envelope can frame —
+/// nothing written included — ends as a `Trap`: with no record to read,
+/// there is nothing a frontend could attribute.
+///
+/// Closed rather than `#[non_exhaustive]`: an invocation either returned
+/// a result or failed to, and there is no third way for one to end. A
+/// wildcard would only hide a frontend that had not been told otherwise.
 pub enum Completion {
-    Outcome(Vec<u8>),
+    Outcome(Outcome),
     Trap(Trap),
 }
 

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

@@ -4,19 +4,22 @@
 //! During a guest→host dispatch, a Service method may yield to a guest
 //! block. The host drives that re-entry through a `Yielder`: it ships the
 //! yield-arguments payload into the in-flight guest and returns the
-//! Yield Reply bytes. What backs the re-entry — a wasmtime `Caller`, some
+//! decoded Yield Reply. What backs the re-entry — a wasmtime `Caller`, some
 //! other engine handle — is the implementer's concern; the dispatch
 //! contract sees only this trait.
 
+use kobako_transport::envelope::YieldReply;
+
 use crate::error::Trap;
 
 /// Host-initiated re-entry into the in-flight guest instance to run a
 /// yielded block.
 ///
-/// `yield_to_block` ships `args` to `__kobako_yield_to_block` and returns
-/// the raw Yield Reply bytes, or a `Trap` — surfaced through the frontend's
-/// trap-error mapping — when the re-entry traps, the guest returns an empty
-/// result, or a payload exceeds the 16 MiB cap.
+/// `yield_to_block` ships `args` as a `yield` downcall and returns the
+/// decoded Yield Reply, `Unsupported` arm included, or a `Trap` — surfaced
+/// through the frontend's trap-error mapping — when the re-entry traps,
+/// the guest returns an empty or unframeable result, or a payload exceeds
+/// the 16 MiB cap.
 pub trait Yielder {
-    fn yield_to_block(&mut self, args: &[u8]) -> Result<Vec<u8>, Trap>;
+    fn yield_to_block(&mut self, args: &[u8]) -> Result<YieldReply, Trap>;
 }

data/crates/kobako-transport/CHANGELOG.md

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

data/crates/kobako-transport/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "kobako-transport"
-version = "0.17.0"
+version = "0.18.0"
 edition = "2021"
 description = "The kobako core envelope — the fixed host↔guest wire frame every assembly shares."
 license = "Apache-2.0"

data/crates/kobako-transport/README.md

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

data/crates/kobako-transport/src/abi.rs

@@ -1,20 +1,19 @@
 //! The ABI's fixed values — the numbers and layouts a host and a guest
 //! must already agree on before either can read the other's bytes.
 //!
-//! The exports and the host import that carry the ABI are declared where
-//! they are implemented: the guest contract crate emits the exports, the
-//! driver resolves them. What lives here is what both sides must spell the
+//! The symbols that carry the ABI are declared where they are
+//! implemented: the guest contract crate emits the exports, the driver
+//! resolves them and provides the import. What lives here is what both sides must spell the
 //! same way, and each value is spelled once.
-//!
-//! [ABI signatures]: ../../../docs/wire-codec.md
 
 /// The Guest ABI version. A host accepts a Guest Binary only when the
-/// version it reports equals this one, so a wire change is an increment
-/// rather than a negotiation.
-pub const ABI_VERSION: u32 = 3;
+/// version it reports equals this one, so a framing or symbol change is
+/// an increment rather than a negotiation. A new request tag needs
+/// neither, but a new answer arm is an increment.
+pub const ABI_VERSION: u32 = 4;
 
-/// Width in bytes of the length prefix that precedes each invocation-channel
-/// frame and the outcome buffer.
+/// Width in bytes of the length prefix that frames a message on WASI
+/// stdin, such as the Preamble.
 pub const FRAME_LEN_SIZE: usize = 4;
 
 /// Single-dispatch size cap: 16 MiB in either direction, applied to the
@@ -26,16 +25,14 @@ pub const MAX_DISPATCH_PAYLOAD: usize = 16 * 1024 * 1024;
 /// length before it can check anything else about it, so this bounds what a
 /// declared length may make it allocate. It sits above
 /// `MAX_DISPATCH_PAYLOAD` because it guards the read rather than enforcing
-/// the contract: a frame between the two is allocated and then refused on
-/// its merits.
+/// the contract: the host enforces the 16 MiB cap before it sends a frame.
 pub const MAX_FRAME_LEN: usize = 64 * 1024 * 1024;
 
 // The read guard must admit every frame the contract allows, so a refusal
 // names the cap rather than the allocation ceiling.
 const _: () = assert!(MAX_FRAME_LEN > MAX_DISPATCH_PAYLOAD);
 
-/// Pack `(ptr, len)` into the u64 the ABI's three buffer-returning
-/// functions answer with: the high 32 bits carry the linear-memory pointer,
+/// Pack `(ptr, len)` into the u64 the downcall and the upcall answer with: the high 32 bits carry the linear-memory pointer,
 /// the low 32 the byte length. A `len` of zero is the failure signal.
 ///
 /// ```text

data/crates/kobako-transport/src/envelope/bytes.rs

@@ -54,21 +54,33 @@ impl<'a> Reader<'a> {
     }
 
     /// A `u32` count followed by that many byte strings, each carrying
-    /// UTF-8. Every list the envelope defines is a list of names, so this
-    /// is the only list shape a reader needs.
+    /// UTF-8.
     ///
     /// The elements are copied rather than borrowed: a binding's path and
     /// a panic's `available` names outlive the frame buffer they arrive in.
     pub(crate) fn text_list(&mut self) -> Result<Vec<String>, DecodeError> {
+        self.list(|reader| Ok(reader.text()?.to_owned()))
+    }
+
+    /// A `u32` count followed by that many byte strings of any content,
+    /// copied for the same reason as `text_list`.
+    pub(crate) fn bytes_list(&mut self) -> Result<Vec<Vec<u8>>, DecodeError> {
+        self.list(|reader| Ok(reader.bytes()?.to_vec()))
+    }
+
+    fn list<T>(
+        &mut self,
+        mut element: impl FnMut(&mut Self) -> Result<T, DecodeError>,
+    ) -> Result<Vec<T>, DecodeError> {
         let count = self.u32()? as usize;
-        // A count larger than the bytes left cannot be satisfied; refusing
-        // it here bounds the allocation below by the message size.
-        if count > self.remaining().len() {
+        // Every element opens with a `u32` length, so a count past what the
+        // bytes left can hold is refused before it sizes the allocation.
+        if count > self.remaining().len() / size_of::<u32>() {
             return Err(MALFORMED);
         }
         let mut out = Vec::with_capacity(count);
         for _ in 0..count {
-            out.push(self.text()?.to_owned());
+            out.push(element(self)?);
         }
         Ok(out)
     }