vihaco_runtime/build_message.rs
1// SPDX-FileCopyrightText: 2026 The vihaco Authors
2// SPDX-License-Identifier: MIT
3
4use crate::{Execute, Field, NoMessage};
5
6/// Build execution input for one composite field route and instruction type.
7///
8/// Available with the experimental `typed-declarations` feature. The selected
9/// child's [`Execute<I>`] implementation determines the message type. The `M`
10/// parameter defaults to that associated type. `Context` defaults to `()`;
11/// runners can instead supply immutable runtime data such as a borrowed module.
12/// Consumers can write `C: BuildMessage<F, I, Context>`.
13///
14/// Composite authors implement this trait to choose how their specific machine
15/// builds each message. The body of `build_message` can construct the input
16/// directly or explicitly delegate to a message's [`ReusableMessageRecipe`].
17/// Standard messages, including [`NoMessage`] and typed stack inputs, provide
18/// recipes but do not automatically implement this trait for a composite.
19///
20/// Specify `M` explicitly in those implementations, such as
21/// `BuildMessage<F, Call, (), FunctionInfo>`. Distinct explicit message types
22/// can separate generic builders for different input shapes. The equality bound
23/// requires `M` to match the child's execution message; it cannot select a
24/// different one.
25///
26/// A [`crate::Step`] implementation can use this optional helper to separate
27/// message construction from execution and effect handling. Implementing this
28/// trait neither executes an instruction nor supplies a `Step` implementation.
29///
30/// ```
31/// use vihaco_runtime::{BuildMessage, Execute, Field};
32///
33/// fn prepare<C, F, I>(
34/// composite: &mut C,
35/// instruction: &I,
36/// ) -> vihaco_runtime::eyre::Result<<C::Child as Execute<I>>::Message>
37/// where
38/// C: BuildMessage<F, I>,
39/// C::Child: Execute<I>,
40/// {
41/// composite.build_message(instruction, &())
42/// }
43/// ```
44pub trait BuildMessage<
45 F,
46 I,
47 Context: ?Sized = (),
48 M = <<Self as Field<F>>::Child as Execute<I>>::Message,
49>: Field<F> where
50 Self::Child: Execute<I, Message = M>,
51{
52 /// Resolve and validate the input needed to execute `instruction`.
53 ///
54 /// The builder may mutate the composite, for example by consuming stack
55 /// operands. Mutations made before an error are retained.
56 ///
57 /// # Errors
58 ///
59 /// Returns message-preparation failures, such as invalid program references
60 /// or missing runtime inputs. Callers can propagate the original report
61 /// through [`crate::Step`] before invoking the child.
62 fn build_message(&mut self, instruction: &I, context: &Context) -> eyre::Result<M>;
63}
64
65/// Reusable message construction over machines with specified capabilities.
66///
67/// Upstream message authors implement this trait generically over `Parent`,
68/// requiring capabilities such as [`crate::Field`] or operand-stack access
69/// instead of depending on a particular composite type. `Route` identifies the
70/// destination device, `I` supplies instruction data, and `Context` supplies
71/// shared read-only runtime data. Context may be unsized.
72///
73/// A recipe does not provide a [`BuildMessage`] implementation. Composite
74/// authors choose whether to call `Self::prepare` on the message type from the
75/// body of their own `BuildMessage::build_message` implementation, or construct
76/// the message using machine-specific logic instead.
77///
78/// Available with the experimental `typed-declarations` feature. "Reusable"
79/// describes the intended use; implementations may also name a concrete parent.
80pub trait ReusableMessageRecipe<Parent, Route, I, Context: ?Sized>: Sized {
81 /// Construct the message from the parent's capabilities and runtime inputs.
82 ///
83 /// # Errors
84 ///
85 /// Returns construction or validation failures. Mutations made before an
86 /// error, including successful operand pops, are retained.
87 fn prepare(parent: &mut Parent, instruction: &I, context: &Context) -> eyre::Result<Self>;
88}
89
90impl<C, F, I, Context: ?Sized> ReusableMessageRecipe<C, F, I, Context> for NoMessage
91where
92 C: Field<F>,
93 C::Child: Execute<I, Message = NoMessage>,
94{
95 #[inline]
96 fn prepare(_: &mut C, _: &I, _: &Context) -> eyre::Result<Self> {
97 Ok(NoMessage::new())
98 }
99}