monoloop_contracts/
limits.rs

1//! Bounded transport, interpretation, input, tool, and transaction limits.
2
3use serde::{Deserialize, Serialize};
4use std::time::Duration;
5use thiserror::Error;
6
7/// Input/output buffer bounds for one connection.
8#[derive(Clone, Debug, PartialEq, Eq)]
9pub struct TransportBufferLimits {
10    /// Maximum queued input bytes awaiting send.
11    pub max_queued_input_bytes: usize,
12    /// Maximum queued output bytes awaiting receive.
13    pub max_queued_output_bytes: usize,
14    /// Maximum individual chunk accepted from the caller.
15    pub max_chunk_bytes: usize,
16}
17
18impl Default for TransportBufferLimits {
19    fn default() -> Self {
20        Self {
21            max_queued_input_bytes: 1024 * 1024,
22            max_queued_output_bytes: 1024 * 1024,
23            max_chunk_bytes: 256 * 1024,
24        }
25    }
26}
27
28/// Connector-level limits applied at open.
29#[derive(Clone, Debug)]
30pub struct ConnectorLimits {
31    /// Connect / open deadline.
32    pub connect_deadline: Duration,
33    /// Buffer bounds.
34    pub buffers: TransportBufferLimits,
35    /// Cancellation grace before forced terminate (caller policy may override).
36    pub cancel_grace: Duration,
37    /// Cleanup deadline after terminal selection.
38    pub cleanup_deadline: Duration,
39}
40
41impl Default for ConnectorLimits {
42    fn default() -> Self {
43        Self {
44            connect_deadline: Duration::from_secs(30),
45            buffers: TransportBufferLimits::default(),
46            cancel_grace: Duration::from_secs(5),
47            cleanup_deadline: Duration::from_secs(10),
48        }
49    }
50}
51
52/// Interpretation assembly and output bounds.
53#[derive(Clone, Debug)]
54pub struct InterpretationLimits {
55    /// Maximum undecoded/raw buffer bytes.
56    pub max_undecoded_bytes: usize,
57    /// Maximum dialect frame bytes.
58    pub max_frame_bytes: usize,
59    /// Maximum sentence assembly buffer.
60    pub max_sentence_assembly_bytes: usize,
61    /// Maximum structural atom bytes.
62    pub max_structural_atom_bytes: usize,
63    /// Maximum pending tool actions.
64    pub max_pending_tool_actions: usize,
65    /// Maximum bytes per pending tool action.
66    pub max_bytes_per_tool_action: usize,
67    /// Maximum canonical output queue items.
68    pub max_output_queue_items: usize,
69    /// Maximum safe diagnostics retained.
70    pub max_safe_diagnostics: usize,
71}
72
73impl Default for InterpretationLimits {
74    fn default() -> Self {
75        Self {
76            max_undecoded_bytes: 4 * 1024 * 1024,
77            max_frame_bytes: 4 * 1024 * 1024,
78            max_sentence_assembly_bytes: 256 * 1024,
79            max_structural_atom_bytes: 512 * 1024,
80            max_pending_tool_actions: 256,
81            max_bytes_per_tool_action: 256 * 1024,
82            max_output_queue_items: 4096,
83            max_safe_diagnostics: 64,
84        }
85    }
86}
87
88/// Bounds for validating [`crate::input::CanonicalInput`].
89#[derive(Clone, Debug, PartialEq, Eq)]
90pub struct InputLimits {
91    /// Maximum messages in one input.
92    pub max_messages: usize,
93    /// Maximum text parts per message.
94    pub max_content_parts: usize,
95    /// Maximum bytes of one text part.
96    pub max_text_part_bytes: usize,
97    /// Maximum aggregate UTF-8 bytes of all text parts.
98    pub max_aggregate_text_bytes: usize,
99    /// Maximum assistant tool calls in one input.
100    pub max_tool_calls: usize,
101    /// Maximum JSON argument bytes per tool call.
102    pub max_tool_argument_bytes: usize,
103    /// Maximum JSON nesting depth for tool arguments.
104    pub max_json_depth: u32,
105    /// Maximum optional `name` field bytes.
106    pub max_name_bytes: usize,
107    /// Maximum `tool_call_id` bytes.
108    pub max_tool_call_id_bytes: usize,
109}
110
111impl Default for InputLimits {
112    fn default() -> Self {
113        Self {
114            max_messages: 256,
115            max_content_parts: 64,
116            max_text_part_bytes: 256 * 1024,
117            max_aggregate_text_bytes: 2 * 1024 * 1024,
118            max_tool_calls: 64,
119            max_tool_argument_bytes: 256 * 1024,
120            max_json_depth: 16,
121            max_name_bytes: 128,
122            max_tool_call_id_bytes: 128,
123        }
124    }
125}
126
127/// Extension map bounds (invocation and session configuration).
128#[derive(Clone, Debug, PartialEq, Eq)]
129pub struct ExtensionLimits {
130    /// Maximum number of extension keys.
131    pub max_keys: usize,
132    /// Maximum key string bytes.
133    pub max_key_bytes: usize,
134    /// Maximum nesting depth of extension values.
135    pub max_value_depth: u32,
136    /// Maximum total serialized JSON bytes of all extensions.
137    pub max_serialized_bytes: usize,
138}
139
140impl Default for ExtensionLimits {
141    fn default() -> Self {
142        Self {
143            max_keys: 32,
144            max_key_bytes: 64,
145            max_value_depth: 8,
146            max_serialized_bytes: 16 * 1024,
147        }
148    }
149}
150
151/// Per-tool execution bounds.
152#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
153pub struct ToolLimits {
154    /// Maximum concurrent executions of this tool.
155    pub max_concurrent: usize,
156    /// Maximum input payload bytes.
157    pub max_input_bytes: usize,
158    /// Maximum output payload bytes.
159    pub max_output_bytes: usize,
160    /// Maximum execution wall time.
161    #[serde(with = "duration_secs")]
162    pub execution_deadline: Duration,
163}
164
165impl Default for ToolLimits {
166    fn default() -> Self {
167        Self {
168            max_concurrent: 8,
169            max_input_bytes: 256 * 1024,
170            max_output_bytes: 256 * 1024,
171            execution_deadline: Duration::from_secs(60),
172        }
173    }
174}
175
176/// Per-Channel capacity and encoding bounds.
177#[derive(Clone, Debug, PartialEq, Eq)]
178pub struct ChannelLimits {
179    /// Maximum concurrent active transactions on this Channel.
180    pub max_active_transactions: usize,
181    /// Maximum concurrent distinct sessions.
182    pub max_distinct_sessions: usize,
183    /// Maximum encoded exchange bytes.
184    pub max_encoded_exchange_bytes: usize,
185}
186
187impl Default for ChannelLimits {
188    fn default() -> Self {
189        Self {
190            max_active_transactions: 64,
191            max_distinct_sessions: 64,
192            max_encoded_exchange_bytes: 4 * 1024 * 1024,
193        }
194    }
195}
196
197/// Runtime transaction bounds (see implementation §12).
198#[derive(Clone, Debug, PartialEq, Eq)]
199pub struct TransactionLimits {
200    /// Global active transaction cap.
201    pub max_active_transactions: usize,
202    /// Per-Channel active cap (enforced with Channel limits).
203    pub max_active_per_channel: usize,
204    /// Supervisor control queue items (`ControlCommand` / D-015 remap).
205    pub max_actor_commands: usize,
206    /// Reserved; not a product-enforced byte bound (D-057 — closed-enum control messages).
207    pub max_actor_command_bytes: usize,
208    /// Runtime ceiling on caller [`crate::delivery::DeliveryLimits::max_event_items`].
209    /// Admission rejects delivery ports that exceed this item capacity.
210    pub max_event_queue: usize,
211    /// Runtime ceiling on caller [`crate::delivery::DeliveryLimits::max_event_bytes`].
212    /// Admission rejects delivery ports that exceed this byte capacity.
213    pub max_event_queue_bytes: usize,
214    /// Maximum input aggregate bytes (admission).
215    pub max_input_bytes: usize,
216    /// Maximum messages.
217    pub max_messages: usize,
218    /// Maximum content parts per message.
219    pub max_content_parts: usize,
220    /// Maximum tools selected on one transaction.
221    pub max_tools_per_transaction: usize,
222    /// Maximum tool input-schema JSON bytes (enforced at `StartedRuntime::start`).
223    pub max_tool_schema_bytes: usize,
224    /// Maximum tool payload bytes.
225    pub max_tool_payload_bytes: usize,
226    /// Maximum tool output bytes.
227    pub max_tool_output_bytes: usize,
228    /// Concurrent tools per transaction.
229    pub max_concurrent_tools_per_transaction: usize,
230    /// Queued tool starts per transaction.
231    pub max_queued_tools_per_transaction: usize,
232    /// Maximum inline continuations.
233    pub max_continuations: usize,
234    /// Maximum provider exchanges.
235    pub max_provider_exchanges: usize,
236    /// Maximum continuation-context encoded bytes.
237    pub max_continuation_context_bytes: usize,
238    /// Maximum total provider input bytes across exchanges.
239    pub max_total_provider_input_bytes: usize,
240    /// Maximum total provider output bytes across exchanges.
241    pub max_total_provider_output_bytes: usize,
242    /// Maximum retained diagnostics.
243    pub max_diagnostic_count: usize,
244    /// Maximum bytes per diagnostic message.
245    pub max_diagnostic_bytes: usize,
246    /// Default transaction deadline.
247    pub transaction_deadline: Duration,
248    /// Cleanup budget after terminal selection.
249    pub cleanup_deadline: Duration,
250    /// Terminal `Ended` delivery budget.
251    pub terminal_event_delivery_deadline: Duration,
252    /// Reserved callback budget (D-059 — no core wait site under M7 push completion).
253    pub callback_deadline: Duration,
254}
255
256impl Default for TransactionLimits {
257    fn default() -> Self {
258        Self {
259            max_active_transactions: 256,
260            max_active_per_channel: 64,
261            max_actor_commands: 256,
262            max_actor_command_bytes: 1024 * 1024,
263            max_event_queue: 1024,
264            max_event_queue_bytes: 4 * 1024 * 1024,
265            max_input_bytes: 2 * 1024 * 1024,
266            max_messages: 256,
267            max_content_parts: 64,
268            max_tools_per_transaction: 64,
269            max_tool_schema_bytes: 64 * 1024,
270            max_tool_payload_bytes: 256 * 1024,
271            max_tool_output_bytes: 256 * 1024,
272            max_concurrent_tools_per_transaction: 16,
273            max_queued_tools_per_transaction: 64,
274            max_continuations: 32,
275            max_provider_exchanges: 64,
276            max_continuation_context_bytes: 2 * 1024 * 1024,
277            max_total_provider_input_bytes: 16 * 1024 * 1024,
278            max_total_provider_output_bytes: 16 * 1024 * 1024,
279            max_diagnostic_count: 64,
280            max_diagnostic_bytes: 1024,
281            transaction_deadline: Duration::from_secs(600),
282            cleanup_deadline: Duration::from_secs(30),
283            terminal_event_delivery_deadline: Duration::from_secs(10),
284            callback_deadline: Duration::from_secs(5),
285        }
286    }
287}
288
289/// Limit configuration rejected before runtime start.
290#[derive(Clone, Debug, Error, PartialEq, Eq)]
291pub enum LimitsError {
292    /// A capacity is zero where non-zero is required.
293    #[error("limit must be non-zero: {0}")]
294    ZeroCapacity(&'static str),
295    /// Related limits are inconsistent.
296    #[error("inconsistent limits: {0}")]
297    Inconsistent(&'static str),
298}
299
300mod duration_secs {
301    use serde::{Deserialize, Deserializer, Serialize, Serializer};
302    use std::time::Duration;
303
304    pub fn serialize<S>(d: &Duration, serializer: S) -> Result<S::Ok, S::Error>
305    where
306        S: Serializer,
307    {
308        d.as_secs().serialize(serializer)
309    }
310
311    pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
312    where
313        D: Deserializer<'de>,
314    {
315        let secs = u64::deserialize(deserializer)?;
316        Ok(Duration::from_secs(secs))
317    }
318}
319
320impl TransactionLimits {
321    /// Validate non-zero capacities and basic consistency (D-015).
322    pub fn validate(&self) -> Result<(), LimitsError> {
323        for (name, v) in [
324            ("max_active_transactions", self.max_active_transactions),
325            ("max_active_per_channel", self.max_active_per_channel),
326            ("max_actor_commands", self.max_actor_commands),
327            ("max_actor_command_bytes", self.max_actor_command_bytes),
328            ("max_event_queue", self.max_event_queue),
329            ("max_event_queue_bytes", self.max_event_queue_bytes),
330            ("max_input_bytes", self.max_input_bytes),
331            ("max_messages", self.max_messages),
332            ("max_content_parts", self.max_content_parts),
333            ("max_tools_per_transaction", self.max_tools_per_transaction),
334            ("max_tool_schema_bytes", self.max_tool_schema_bytes),
335            ("max_tool_payload_bytes", self.max_tool_payload_bytes),
336            ("max_tool_output_bytes", self.max_tool_output_bytes),
337            (
338                "max_concurrent_tools_per_transaction",
339                self.max_concurrent_tools_per_transaction,
340            ),
341            (
342                "max_queued_tools_per_transaction",
343                self.max_queued_tools_per_transaction,
344            ),
345            ("max_continuations", self.max_continuations.max(1)), // 0 continuations allowed
346            ("max_provider_exchanges", self.max_provider_exchanges),
347            (
348                "max_continuation_context_bytes",
349                self.max_continuation_context_bytes,
350            ),
351            (
352                "max_total_provider_input_bytes",
353                self.max_total_provider_input_bytes,
354            ),
355            (
356                "max_total_provider_output_bytes",
357                self.max_total_provider_output_bytes,
358            ),
359            ("max_diagnostic_count", self.max_diagnostic_count),
360            ("max_diagnostic_bytes", self.max_diagnostic_bytes),
361        ] {
362            // Continuations may be zero (CallerControlled-only channels).
363            if name == "max_continuations" {
364                continue;
365            }
366            if v == 0 {
367                return Err(LimitsError::ZeroCapacity(name));
368            }
369        }
370        if self.callback_deadline.is_zero() {
371            return Err(LimitsError::ZeroCapacity("callback_deadline"));
372        }
373        if self.cleanup_deadline.is_zero() {
374            return Err(LimitsError::ZeroCapacity("cleanup_deadline"));
375        }
376        if self.terminal_event_delivery_deadline.is_zero() {
377            return Err(LimitsError::ZeroCapacity(
378                "terminal_event_delivery_deadline",
379            ));
380        }
381        if self.transaction_deadline.is_zero() {
382            return Err(LimitsError::ZeroCapacity("transaction_deadline"));
383        }
384        if self.max_active_per_channel > self.max_active_transactions {
385            return Err(LimitsError::Inconsistent(
386                "max_active_per_channel exceeds max_active_transactions",
387            ));
388        }
389        if self.max_event_queue_bytes < self.max_event_queue {
390            return Err(LimitsError::Inconsistent(
391                "max_event_queue_bytes smaller than max_event_queue items",
392            ));
393        }
394        Ok(())
395    }
396}
monoloop_contracts/limits.rs

monoloop_contracts/
limits.rs
