kobako 0.27.0 → 0.29.0

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

@@ -0,0 +1,178 @@
+//! A Mount: the Grant handing a Filesystem to the guest at an absolute
+//! guest path, with the access it allows there. The Mount decides each
+//! open and each change itself, so a runtime asks it rather than reading
+//! its access, and a Filesystem of a third party's checks nothing.
+
+use std::fmt;
+use std::sync::Arc;
+
+use crate::filesystem::{Access, Filesystem};
+
+/// The Host App's decision for one path a guest opens or changes, made in
+/// a Mount's access's place.
+pub trait Policy: Send + Sync {
+    /// Whether the guest may reach `path`, the absolute guest path, with
+    /// `access`.
+    fn allows(&self, path: &str, access: Access) -> bool;
+}
+
+/// Why a Mount refused a call.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Denial {
+    /// A change beneath a Mount allowing only reads.
+    ReadOnly,
+    /// The Mount's Policy said no.
+    Refused,
+}
+
+/// A Filesystem at an absolute guest path. Its path bounds what a Policy
+/// can allow either way.
+#[derive(Clone)]
+pub struct Mount {
+    at: String,
+    access: Access,
+    filesystem: Arc<dyn Filesystem>,
+    policy: Option<Arc<dyn Policy>>,
+}
+
+/// A path no Mount can stand at: one that is not an absolute guest path.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MountPathError(String);
+
+impl fmt::Display for MountPathError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "mount path must be an absolute guest path, got {:?}",
+            self.0
+        )
+    }
+}
+
+impl std::error::Error for MountPathError {}
+
+/// An absolute guest path has no empty, `.`, or `..` component; the root
+/// is `/` alone.
+fn is_guest_path(at: &str) -> bool {
+    at == "/"
+        || at.strip_prefix('/').is_some_and(|rest| {
+            rest.split('/')
+                .all(|part| !part.is_empty() && part != "." && part != "..")
+        })
+}
+
+impl Mount {
+    /// A Mount of `filesystem` at `at`, refused unless `at` is an absolute
+    /// guest path, which every path the Mount answers for is built on.
+    pub fn new(
+        at: impl Into<String>,
+        filesystem: Arc<dyn Filesystem>,
+        access: Access,
+    ) -> Result<Self, MountPathError> {
+        let at = at.into();
+        if !is_guest_path(&at) {
+            return Err(MountPathError(at));
+        }
+        Ok(Self {
+            at,
+            access,
+            filesystem,
+            policy: None,
+        })
+    }
+
+    /// This Mount with `policy` deciding each open and each change in its
+    /// access's place.
+    pub fn with_policy(self, policy: Arc<dyn Policy>) -> Self {
+        Self {
+            policy: Some(policy),
+            ..self
+        }
+    }
+
+    /// The absolute guest path the Filesystem appears at.
+    pub fn at(&self) -> &str {
+        &self.at
+    }
+
+    /// The Filesystem an engine hands each call beneath this Mount.
+    pub fn filesystem(&self) -> &Arc<dyn Filesystem> {
+        &self.filesystem
+    }
+
+    /// Whether a change beneath this Mount may be allowed at all: it was made
+    /// to be written, or a Policy decides each change in its access's place.
+    /// The Policy itself is not asked.
+    pub fn allows_writes(&self) -> bool {
+        self.policy.is_some() || self.access == Access::ReadWrite
+    }
+
+    /// The absolute guest path `path`, relative to this Mount's root,
+    /// stands for.
+    pub fn guest_path(&self, path: &str) -> String {
+        match (self.at.as_str(), path) {
+            (at, "") => at.to_string(),
+            ("/", path) => format!("/{path}"),
+            (at, path) => format!("{at}/{path}"),
+        }
+    }
+
+    /// Whether the guest may reach `path`, relative to this Mount's root,
+    /// with `access`. A Policy judges the path as the Filesystem stores
+    /// its names, so a host folding case or Unicode form cannot hand it
+    /// one spelling of an entry it refuses by another; a Filesystem that
+    /// cannot spell it refuses.
+    pub fn check(&self, path: &str, access: Access) -> Result<(), Denial> {
+        match &self.policy {
+            Some(policy) => {
+                let stored = self
+                    .filesystem
+                    .stored_path(path)
+                    .map_err(|_| Denial::Refused)?;
+                if policy.allows(&self.guest_path(&stored), access) {
+                    Ok(())
+                } else {
+                    Err(Denial::Refused)
+                }
+            }
+            None if access == Access::ReadWrite && self.access == Access::Read => {
+                Err(Denial::ReadOnly)
+            }
+            None => Ok(()),
+        }
+    }
+
+    /// Whether a directory may move beneath this Mount. Under a Policy it
+    /// may not: everything beneath it would take paths the Policy never
+    /// judged, so a move is refused as one across devices and the guest
+    /// copies entry by entry instead, as Landlock refuses such a move.
+    pub fn moves_directories(&self) -> bool {
+        self.policy.is_none()
+    }
+
+    /// Whether a path beneath this Mount may pass through a link the
+    /// Filesystem holds. Under a Policy it may not: the link leads to a
+    /// path the Policy never judged, so the call is refused as one past
+    /// too many links.
+    pub fn follows_links(&self) -> bool {
+        self.policy.is_none()
+    }
+
+    /// This Mount as a new Invocation starts from it, over the Filesystem
+    /// that Invocation receives; beneath a Policy, the one that follows no
+    /// link, so each call reaches the path the Policy judged.
+    pub fn for_invocation(&self) -> Self {
+        let filesystem = self
+            .filesystem
+            .for_invocation()
+            .unwrap_or_else(|| self.filesystem.clone());
+        let filesystem = match self.policy {
+            Some(_) => filesystem.for_policy().unwrap_or(filesystem),
+            None => filesystem,
+        };
+        Self {
+            filesystem,
+            ..self.clone()
+        }
+    }
+}

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

@@ -9,10 +9,10 @@
 /// The ordered isolation ladder a runtime builds one rung of.
 ///
 /// `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 —
-/// live ambient time and entropy at the WASI boundary. Ordering
+/// entropy denied at the WASI boundary, no ambient filesystem /
+/// environment / network reachability, and no host import beyond the wire ABI's
+/// `__kobako_upcall`. `Permissive` differs only in the ambient
+/// authority it grants — live 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,32 @@
 
 use std::sync::Arc;
 
+use kobako_transport::envelope::Preamble;
+
 use crate::dispatch::DispatchHandler;
 use crate::error::InvokeError;
+use crate::grant::{Grant, GrantKind};
 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
@@ -47,16 +50,39 @@ pub struct Frames<'a> {
 /// wrapper and GC-marking it; the runtime itself touches no frontend
 /// value.
 pub trait Runtime {
+    /// `grants` are this Invocation's, each of a kind `supports` declared;
+    /// the runtime presents them to the guest and keeps none afterwards.
     fn invoke(
         &self,
         entry: Entry<'_>,
-        frames: Frames<'_>,
+        preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
+        grants: &[Grant],
     ) -> Result<Snapshot, InvokeError>;
 
+    /// Whether this runtime presents a Grant of `kind` to the guest. A
+    /// frontend refuses to register one it does not, before any guest runs.
+    /// The default supports none, so an engine that has not learned Grants
+    /// still serves every invocation without one.
+    fn supports(&self, _kind: GrantKind) -> bool {
+        false
+    }
+
     /// The isolation profile this runtime provides. Deliberately
     /// without a default: every engine states its posture explicitly,
     /// 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,44 +4,49 @@
 //! 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
 /// pre-invocation sentinel — no bytes, cap not reached — shared by every
 /// frontend's before-first-invocation readout.
 #[derive(Default)]
+#[non_exhaustive]
 pub struct Capture {
     pub bytes: Vec<u8>,
     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),
 }
 
-/// Resource usage of one guest invocation, measured across the same
-/// bracket as the wall-clock / memory caps: `wall_time` is the seconds
-/// spent inside the guest export call; `memory_peak` is the high-water
-/// `memory.grow` delta in bytes past the entry-time baseline. `Default`
-/// (all zeros) is the pre-invocation sentinel.
+/// Resource usage of one guest invocation, each measured across the span
+/// its cap governs: `wall_time` is the seconds from setting the guest up to
+/// its export call returning, the span the deadline covers; `memory_peak`
+/// is the high-water `memory.grow` delta in bytes past the entry-time
+/// baseline. `Default` (all zeros) is the pre-invocation sentinel.
 #[derive(Clone, Copy, Default)]
+#[non_exhaustive]
 pub struct Usage {
     pub wall_time: f64,
     pub memory_peak: usize,
@@ -51,9 +56,22 @@ pub struct Usage {
 /// kinds: captures and usage are collected on trap and outcome alike.
 /// What a frontend exposes from the trap path is its own contract
 /// decision.
+#[non_exhaustive]
 pub struct Snapshot {
     pub completion: Completion,
     pub stdout: Capture,
     pub stderr: Capture,
     pub usage: Usage,
 }
+
+impl Snapshot {
+    /// What an engine hands back from one invocation.
+    pub fn new(completion: Completion, stdout: Capture, stderr: Capture, usage: Usage) -> Self {
+        Self {
+            completion,
+            stdout,
+            stderr,
+            usage,
+        }
+    }
+}

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

@@ -4,19 +4,27 @@
 //! 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.
+/// Each open Call has a `frame`, counted from `0` at the outermost.
+/// `yield_to_block` ships `args` as a `yield` downcall to the block of the
+/// open Call `frame` names, 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>;
+    /// The frame of the Call this Yielder was lent for.
+    fn frame(&self) -> u32;
+
+    fn yield_to_block(&mut self, frame: u32, args: &[u8]) -> Result<YieldReply, Trap>;
 }

data/crates/kobako-transport/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.19.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.18.0...kobako-transport-v0.19.0) (2026-10-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* in kobako-transport, YieldReply::Break carries no payload and Reply gains a Break arm, so a Guest Binary built against the earlier version 5 wire must be rebuilt.
+* 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.
+
+### Features
+
+* let a block's break or return unwind a Service as a plain method ([4e9eca0](https://github.com/elct9620/kobako/commit/4e9eca05f1647c8b6409fc00d08317b431c0c648))
+
+
+### Bug Fixes
+
+* run a stored block as the block of the Call that carried it ([bf33dc1](https://github.com/elct9620/kobako/commit/bf33dc1fd40c83498c6c12b0be52b3a835a144cf))
+
+## [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.19.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.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-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 = 5;
 
-/// 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)
     }