kobako 0.28.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_upcall`. `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

@@ -13,6 +13,7 @@ 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;
 
@@ -49,13 +50,24 @@ pub enum Entry<'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<'_>,
         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

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

@@ -18,6 +18,7 @@ use kobako_transport::envelope::Outcome;
 /// 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,
@@ -39,12 +40,13 @@ pub enum Completion {
     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,
@@ -54,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

@@ -15,11 +15,16 @@ use crate::error::Trap;
 /// Host-initiated re-entry into the in-flight guest instance to run a
 /// yielded block.
 ///
-/// `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.
+/// 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<YieldReply, 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,22 @@
 # 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)
 
 

data/crates/kobako-transport/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "kobako-transport"
-version = "0.18.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

@@ -51,7 +51,7 @@ reaches the same types through `kobako-core`.
 
 ```toml
 [dependencies]
-kobako-transport = "0.18.0" # x-release-please-version
+kobako-transport = "0.19.0" # x-release-please-version
 ```
 
 ## License

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

@@ -10,7 +10,7 @@
 /// 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;
+pub const ABI_VERSION: u32 = 5;
 
 /// Width in bytes of the length prefix that frames a message on WASI
 /// stdin, such as the Preamble.

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

@@ -32,7 +32,8 @@ const KIND_BLOCK: u8 = 4;
 pub enum FaultKind {
     /// A Ruby exception raised inside the Service method.
     Runtime,
-    /// The call shape did not fit the method.
+    /// The Service method refused its arguments, whether the call would
+    /// not bind or the method rejected what it was given.
     Argument,
     /// No such member or method.
     Undefined,

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

@@ -243,7 +243,7 @@ mod tests {
         writer.into_bytes()
     }
 
-    fn preamble_of(records: &[Vec<u8>]) -> Vec<u8> {
+    fn preamble_with(records: &[Vec<u8>]) -> Vec<u8> {
         let mut bytes = (records.len() as u32).to_be_bytes().to_vec();
         for record in records {
             bytes.extend_from_slice(record);
@@ -307,7 +307,7 @@ mod tests {
     // @behavior WE-053
     #[test]
     fn an_absent_record_reads_as_empty() {
-        let bytes = preamble_of(&[record(0, 0x07, &encode_flag(&flag("f", "", false)))]);
+        let bytes = preamble_with(&[record(0, 0x07, &encode_flag(&flag("f", "", false)))]);
         let preamble = Preamble::decode(&bytes).expect("a flag-only Preamble must decode");
         assert_eq!(
             (preamble.bindings, preamble.snippets),
@@ -375,7 +375,7 @@ mod tests {
     // @behavior WE-056
     #[test]
     fn an_unknown_snippet_kind_is_refused() {
-        let bytes = preamble_of(&[record(1, 0x06, &[0, 0, 0, 1, 9])]);
+        let bytes = preamble_with(&[record(1, 0x06, &[0, 0, 0, 1, 9])]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a snippet kind that is neither source nor bytecode through Preamble::decode must \
@@ -387,7 +387,7 @@ mod tests {
     #[test]
     fn a_count_the_preamble_cannot_satisfy_is_refused() {
         let records = [0xff, 0xff, 0xff, 0xff];
-        let snippets = preamble_of(&[record(1, 0x06, &[0xff, 0xff, 0xff, 0xff])]);
+        let snippets = preamble_with(&[record(1, 0x06, &[0xff, 0xff, 0xff, 0xff])]);
         assert!(
             Preamble::decode(&records).is_err() && Preamble::decode(&snippets).is_err(),
             "a record or snippet count larger than what follows through Preamble::decode must \
@@ -400,7 +400,7 @@ mod tests {
     fn trailing_bytes_are_refused() {
         let mut past_the_list = Preamble::default().encode();
         past_the_list.push(0);
-        let past_a_body = preamble_of(&[record(1, 0x05, &[0, 0, 0, 0, 0])]);
+        let past_a_body = preamble_with(&[record(1, 0x05, &[0, 0, 0, 0, 0])]);
         assert!(
             Preamble::decode(&past_the_list).is_err() && Preamble::decode(&past_a_body).is_err(),
             "bytes past the last record or past a record body's last field through \
@@ -411,7 +411,7 @@ mod tests {
     // @behavior WE-077
     #[test]
     fn an_advisory_record_of_an_unknown_kind_is_skipped() {
-        let bytes = preamble_of(&[
+        let bytes = preamble_with(&[
             record(0, 0x7e, b"anything"),
             record(
                 1,
@@ -432,7 +432,7 @@ mod tests {
     // @behavior WE-078
     #[test]
     fn a_critical_record_of_an_unknown_kind_is_refused() {
-        let bytes = preamble_of(&[record(1, 0x7e, b"anything")]);
+        let bytes = preamble_with(&[record(1, 0x7e, b"anything")]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a critical record of a kind the registry has not assigned through \
@@ -444,7 +444,7 @@ mod tests {
     #[test]
     fn a_record_kind_assigned_to_another_message_is_refused() {
         for kind in [0x00, 0x01, 0x10] {
-            let bytes = preamble_of(&[record(0, kind, b"")]);
+            let bytes = preamble_with(&[record(0, kind, b"")]);
             assert!(
                 Preamble::decode(&bytes).is_err(),
                 "an advisory record of kind {kind:#04x}, which the registry assigns elsewhere, \
@@ -459,7 +459,7 @@ mod tests {
         let bindings = encode_bindings(&Bindings::default());
         let snippets = encode_snippets(&Snippets::default());
         for (kind, body) in [(0x05, bindings), (0x06, snippets)] {
-            let bytes = preamble_of(&[record(1, kind, &body), record(1, kind, &body)]);
+            let bytes = preamble_with(&[record(1, kind, &body), record(1, kind, &body)]);
             assert!(
                 Preamble::decode(&bytes).is_err(),
                 "a second record of kind {kind:#04x} through Preamble::decode must be refused"
@@ -485,7 +485,7 @@ mod tests {
     // @behavior WE-082
     #[test]
     fn a_criticality_that_is_neither_value_is_refused() {
-        let bytes = preamble_of(&[record(2, 0x07, &encode_flag(&flag("f", "", false)))]);
+        let bytes = preamble_with(&[record(2, 0x07, &encode_flag(&flag("f", "", false)))]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a criticality byte other than 0 or 1 through Preamble::decode must be refused"
@@ -504,8 +504,8 @@ mod tests {
         );
         let flag = record(0, 0x07, &encode_flag(&flag("f", "", false)));
         assert_eq!(
-            Preamble::decode(&preamble_of(&[flag.clone(), bindings.clone()])),
-            Preamble::decode(&preamble_of(&[bindings, flag])),
+            Preamble::decode(&preamble_with(&[flag.clone(), bindings.clone()])),
+            Preamble::decode(&preamble_with(&[bindings, flag])),
             "the same records in another order through Preamble::decode must read as the same \
              Preamble"
         );

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

@@ -17,6 +17,9 @@ pub enum Reply {
     /// every field of a Fault is kobako's, so a guest reads a refusal
     /// whatever schema it speaks.
     Fault(Fault),
+    /// A block exit unwound the method; the guest continues that exit,
+    /// which it kept, so nothing of it crosses.
+    Break,
     /// The receiver does not serve the request it was sent.
     Unsupported(Unsupported),
 }
@@ -29,9 +32,13 @@ impl Reply {
             // No `finish` here: a Fault owns everything after the tag,
             // including the fields a later contract version appends.
             tag::FAULT => Ok(Reply::Fault(Fault::read(&mut reader)?)),
+            tag::BREAK => {
+                reader.finish()?;
+                Ok(Reply::Break)
+            }
             tag::UNSUPPORTED => Ok(Reply::Unsupported(Unsupported::read(&mut reader)?)),
             _ => Err(DecodeError::new(
-                "Reply tag must be 0x10 (ok), 0x11 (fault), or 0x15 (unsupported)",
+                "Reply tag must be 0x10 (ok), 0x11 (fault), 0x12 (break), or 0x15 (unsupported)",
             )),
         }
     }
@@ -46,21 +53,23 @@ impl Reply {
                 writer.u8(tag::FAULT);
                 fault.write(&mut writer);
             }
+            Reply::Break => {
+                writer.u8(tag::BREAK);
+            }
             Reply::Unsupported(refusal) => return refusal.encode(),
         }
         writer.into_bytes()
     }
 }
 
-/// The answer to one Yield Call. Carries a `Break` outcome the dispatch
-/// Reply has no counterpart for, because a block can end its caller.
+/// The answer to one Yield Call.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum YieldReply {
     /// The block completed; the bytes are its value, codec-encoded.
     Ok(Vec<u8>),
-    /// The block ran `break`; the bytes are the break value,
-    /// codec-encoded. It returns to the guest rather than to host code.
-    Break(Vec<u8>),
+    /// The block ran `break` or `return` to a frame past the Service.
+    /// The guest keeps the exit, so the Service is only unwound.
+    Break,
     /// The block raised, or failed in a way the host re-raises at the
     /// yield site.
     Error(ErrorRecord),
@@ -73,7 +82,10 @@ impl YieldReply {
         let mut reader = Reader::new(bytes);
         match reader.u8()? {
             tag::OK => Ok(YieldReply::Ok(reader.remaining().to_vec())),
-            tag::BREAK => Ok(YieldReply::Break(reader.remaining().to_vec())),
+            tag::BREAK => {
+                reader.finish()?;
+                Ok(YieldReply::Break)
+            }
             tag::ERROR => {
                 let record = ErrorRecord::read(&mut reader)?;
                 reader.finish()?;
@@ -90,8 +102,8 @@ impl YieldReply {
             YieldReply::Ok(body) => {
                 writer.u8(tag::OK).remainder(body);
             }
-            YieldReply::Break(body) => {
-                writer.u8(tag::BREAK).remainder(body);
+            YieldReply::Break => {
+                writer.u8(tag::BREAK);
             }
             YieldReply::Error(record) => {
                 writer.u8(tag::ERROR);
@@ -116,6 +128,7 @@ mod tests {
                 super::super::FaultKind::Undefined,
                 "no such method",
             )),
+            Reply::Break,
             Reply::Unsupported(Unsupported::new("no such operation")),
         ] {
             let encoded = reply.encode();
@@ -142,7 +155,7 @@ mod tests {
     #[test]
     fn an_unknown_reply_tag_is_refused() {
         assert!(
-            Reply::decode(&[0x12, 0]).is_err(),
+            Reply::decode(&[0x13, 0]).is_err(),
             "a Reply tag outside its arms must be rejected as a wire violation"
         );
     }
@@ -161,7 +174,7 @@ mod tests {
     fn every_live_yield_arm_round_trips() {
         let arms = [
             YieldReply::Ok(vec![0xa4]),
-            YieldReply::Break(vec![0xa4]),
+            YieldReply::Break,
             YieldReply::Error(ErrorRecord {
                 name: "LocalJumpError".into(),
                 message: "no block".into(),
@@ -214,6 +227,11 @@ mod tests {
             "an unsupported Reply must encode as tag byte 0x15 followed by kind 0 and the \
              message"
         );
+        assert_eq!(
+            Reply::Break.encode(),
+            vec![0x12],
+            "a break Reply must encode as tag byte 0x12 alone, since the guest keeps the exit"
+        );
     }
 
     // @behavior WE-068
@@ -242,9 +260,9 @@ mod tests {
             "a Yield Reply carrying the block's value must encode as tag byte 0x10"
         );
         assert_eq!(
-            YieldReply::Break(vec![0xc0]).encode(),
-            vec![0x12, 0xc0],
-            "a Yield Reply carrying a break value must encode as tag byte 0x12"
+            YieldReply::Break.encode(),
+            vec![0x12],
+            "a Yield Reply for a block exit must encode as tag byte 0x12 alone"
         );
         assert_eq!(
             YieldReply::Unsupported(Unsupported::new("x")).encode(),

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

@@ -18,9 +18,9 @@ pub enum Downcall {
     Eval(Vec<u8>),
     /// Call the entrypoint the Run names.
     Run(Run),
-    /// Re-enter the block bound to the active dispatch; the bytes are
-    /// its arguments, codec-encoded.
-    Yield(Vec<u8>),
+    /// Re-enter the block of the open Call `frame` counts to, from `0`
+    /// at the outermost; `args` are its arguments, codec-encoded.
+    Yield { frame: u32, args: Vec<u8> },
     /// Compile the Preamble's source Snippets without running them. It
     /// carries no body: what it compiles is the Preamble an invocation
     /// would read.
@@ -37,7 +37,10 @@ impl Downcall {
         Ok(match tag {
             tag::EVAL => Downcall::Eval(body.to_vec()),
             tag::RUN => Downcall::Run(Run::decode(body)?),
-            tag::YIELD => Downcall::Yield(body.to_vec()),
+            tag::YIELD => Downcall::Yield {
+                frame: reader.u32()?,
+                args: reader.remaining().to_vec(),
+            },
             tag::COMPILE if body.is_empty() => Downcall::Compile,
             tag::COMPILE => return Err(DecodeError::new("a compile request carries no body")),
             tag => Downcall::Unknown {
@@ -52,7 +55,7 @@ impl Downcall {
         match self {
             Downcall::Eval(source) => writer.u8(tag::EVAL).remainder(source),
             Downcall::Run(run) => writer.u8(tag::RUN).remainder(&run.encode()),
-            Downcall::Yield(args) => writer.u8(tag::YIELD).remainder(args),
+            Downcall::Yield { frame, args } => writer.u8(tag::YIELD).u32(*frame).remainder(args),
             Downcall::Compile => writer.u8(tag::COMPILE),
             Downcall::Unknown { tag, body } => writer.u8(tag.get()).remainder(body),
         };
@@ -146,14 +149,18 @@ mod tests {
             (
                 Downcall::Eval(b"1".to_vec()).encode(),
                 Downcall::Run(run).encode(),
-                Downcall::Yield(vec![0x90]).encode(),
+                Downcall::Yield {
+                    frame: 2,
+                    args: vec![0x90],
+                }
+                .encode(),
                 Downcall::Compile.encode(),
                 Upcall::Call(call).encode(),
             ),
             (
                 vec![0x01, b'1'],
                 vec![0x02, 0, 0, 0, 1, b'M', 0x90],
-                vec![0x03, 0x90],
+                vec![0x03, 0, 0, 0, 2, 0x90],
                 vec![0x08],
                 vec![
                     0x04, // tag: call
@@ -177,7 +184,10 @@ mod tests {
                 entrypoint: "Main".into(),
                 payload: vec![0x90],
             }),
-            Downcall::Yield(vec![0x91, 0x01]),
+            Downcall::Yield {
+                frame: 0,
+                args: vec![0x91, 0x01],
+            },
             Downcall::Compile,
             Downcall::Unknown {
                 tag: UnknownTag::new(0xf0).unwrap(),