tenzro_types/
runtime.rs

1//! RFC-0007: Adaptive Execution Upgrade — Runtime types
2//!
3//! Phase 1 (Metadata Foundation): type annotations, manifest fields, and HTTP API
4//! for the Tenzro adaptive execution runtime. No streaming/MoE runtime logic yet.
5//!
6//! # Backward Compatibility
7//!
8//! All new fields on existing wire messages use `#[serde(default)]`.
9//! Old nodes that do not emit these fields will be treated as
10//! `artifact_completeness = FULL_ONLY` with `execution_support.local_full = true`.
11
12use serde::{Deserialize, Serialize};
13
14// ---------------------------------------------------------------------------
15// Enums
16// ---------------------------------------------------------------------------
17
18/// High-level classification of a model by architecture and parameter scale.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
20#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
21pub enum ModelClass {
22    #[default]
23    SmallDense,
24    MidDense,
25    LargeDense,
26    SmallMoe,
27    LargeMoe,
28    FrontierMoe,
29}
30
31/// How a model session should be executed end-to-end.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
33#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
34pub enum ExecutionMode {
35    /// Full weights loaded locally, inference executed locally.
36    #[default]
37    LocalFull,
38    /// Full weights loaded on a remote node; client sends prompt, receives response.
39    RemoteFull,
40    /// Weights streamed to local memory layer-by-layer during inference.
41    LocalStreamed,
42    /// Remote node uses layer streaming; client receives streamed tokens.
43    RemoteStreamed,
44    /// MoE router local; expert shards distributed across a local cluster.
45    HybridMoeLocal,
46    /// MoE router local; expert shards distributed across a regional mesh.
47    HybridMoeRegional,
48    /// Runtime selects the best mode automatically.
49    Auto,
50}
51
52/// Which artifact types are present for a model, determining execution modes.
53#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
54#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
55pub enum ArtifactCompleteness {
56    /// Only full-weight artifacts — supports LOCAL_FULL / REMOTE_FULL only.
57    #[default]
58    FullOnly,
59    /// Full weights + streaming shards — all non-MoE modes supported.
60    StreamingReady,
61    /// Full weights + expert shards — MoE hybrid modes supported.
62    MoeReady,
63    /// All artifact types present — any execution mode supported.
64    FullyAdaptive,
65}
66
67/// Fine-grained type of a single downloadable artifact.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
69#[serde(rename_all = "snake_case")]
70#[derive(Default)]
71pub enum ArtifactType {
72    #[default]
73    FullWeights,
74    StreamingShard,
75    ExpertShard,
76    KvProfile,
77    Tokenizer,
78    BackendBundle,
79    QuantVariant,
80}
81
82
83/// KV-cache compression profile.
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
85#[serde(rename_all = "snake_case")]
86pub enum KVProfile {
87    /// Raw FP16/BF16 KV cache.
88    #[default]
89    KvRaw,
90    /// INT8-quantised KV cache.
91    KvInt8,
92    /// Mixed-precision KV cache (attention heads split).
93    KvMixed,
94    /// Paged KV cache for variable sequence lengths.
95    KvPaged,
96}
97
98/// Role a node plays in a distributed inference execution plan.
99#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
100#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
101pub enum WorkerRole {
102    /// Runs the full model on a single node.
103    #[default]
104    FullWorker,
105    /// Streams layer shards during inference.
106    StreamingWorker,
107    /// Hosts expert shards in a MoE configuration.
108    ExpertWorker,
109    /// Handles prefill phase of prompt processing.
110    PrefillWorker,
111}
112
113// ---------------------------------------------------------------------------
114// Structs
115// ---------------------------------------------------------------------------
116
117/// Which execution modes a node is capable of serving.
118#[derive(Debug, Clone, Serialize, Deserialize)]
119pub struct ExecutionSupport {
120    /// Node can load full model weights and run inference locally.
121    #[serde(default = "default_true")]
122    pub local_full: bool,
123    /// Node can accept remote inference requests for a full model.
124    #[serde(default = "default_true")]
125    pub remote_full: bool,
126    /// Node can stream model layers for local inference.
127    #[serde(default)]
128    pub local_streamed: bool,
129    /// Node can serve remote inference with layer streaming.
130    #[serde(default)]
131    pub remote_streamed: bool,
132    /// Node can participate as local MoE expert coordinator.
133    #[serde(default)]
134    pub hybrid_moe_local: bool,
135    /// Node can participate in regional MoE mesh.
136    #[serde(default)]
137    pub hybrid_moe_regional: bool,
138}
139
140impl Default for ExecutionSupport {
141    fn default() -> Self {
142        Self {
143            local_full: true,
144            remote_full: true,
145            local_streamed: false,
146            remote_streamed: false,
147            hybrid_moe_local: false,
148            hybrid_moe_regional: false,
149        }
150    }
151}
152
153fn default_true() -> bool {
154    true
155}
156
157/// Internal topology metadata for MoE and large-scale models.
158#[derive(Debug, Clone, Default, Serialize, Deserialize)]
159pub struct ModelTopology {
160    /// Total number of experts (for MoE models).
161    #[serde(default)]
162    pub num_experts: u32,
163    /// Number of experts activated per token.
164    #[serde(default)]
165    pub active_experts: u32,
166    /// Total number of transformer layers.
167    #[serde(default)]
168    pub num_layers: u32,
169    /// Hidden dimension size.
170    #[serde(default)]
171    pub hidden_dim: u32,
172    /// Number of attention heads.
173    #[serde(default)]
174    pub attention_heads: u32,
175}
176
177/// Hardware and network constraints for scheduling inference.
178#[derive(Debug, Clone, Default, Serialize, Deserialize)]
179pub struct PlacementConstraints {
180    /// Minimum VRAM required (GB).
181    #[serde(default)]
182    pub min_vram_gb: u32,
183    /// Minimum system RAM required (GB).
184    #[serde(default)]
185    pub min_ram_gb: u32,
186    /// Must be scheduled on a GPU-enabled node.
187    #[serde(default)]
188    pub requires_gpu: bool,
189    /// Must be scheduled on a TEE-enabled node.
190    #[serde(default)]
191    pub requires_tee: bool,
192    /// Preferred geographic regions (e.g. "us-central1").
193    #[serde(default)]
194    pub preferred_regions: Vec<String>,
195}
196
197/// Routing preferences for inference request dispatch.
198#[derive(Debug, Clone, Serialize, Deserialize)]
199pub struct RoutingPolicy {
200    /// Prefer local execution if a capable node is available.
201    #[serde(default = "default_true")]
202    pub prefer_local: bool,
203    /// Maximum allowed hop count for distributed inference.
204    #[serde(default = "default_max_hops")]
205    pub max_hops: u32,
206    /// Only route to attestation-verified providers.
207    #[serde(default)]
208    pub require_attestation: bool,
209    /// Fall back to remote execution if local is unavailable.
210    #[serde(default = "default_true")]
211    pub fallback_to_remote: bool,
212}
213
214impl Default for RoutingPolicy {
215    fn default() -> Self {
216        Self {
217            prefer_local: true,
218            max_hops: 3,
219            require_attestation: false,
220            fallback_to_remote: true,
221        }
222    }
223}
224
225fn default_max_hops() -> u32 {
226    3
227}
228
229/// Client-specified execution requirements for an inference session.
230#[derive(Debug, Clone, Default, Serialize, Deserialize)]
231pub struct RequiredExecution {
232    /// Minimum acceptable execution mode.
233    #[serde(default)]
234    pub min_mode: ExecutionMode,
235    /// Preferred execution mode.
236    #[serde(default)]
237    pub preferred_mode: ExecutionMode,
238    /// Whether the node may fall back to a less capable mode.
239    #[serde(default = "default_true")]
240    pub allow_fallback: bool,
241}
242
243/// Runtime capabilities declared by a provider node.
244#[derive(Debug, Clone, Default, Serialize, Deserialize)]
245pub struct RuntimeSupport {
246    /// Execution modes this node can serve.
247    #[serde(default)]
248    pub supported_modes: Vec<ExecutionMode>,
249    /// Inference backend identifiers (e.g. "llama.cpp", "vllm", "ggml").
250    #[serde(default)]
251    pub supported_backends: Vec<String>,
252    /// Maximum supported context length in tokens.
253    #[serde(default)]
254    pub max_context_len: u32,
255    /// Maximum request batch size.
256    #[serde(default)]
257    pub max_batch_size: u32,
258    /// Whether this node has a verified TEE enclave.
259    #[serde(default)]
260    pub tee_capable: bool,
261}
262
263/// TEE trust provenance for a provider or inference session.
264#[derive(Debug, Clone, Default, Serialize, Deserialize)]
265pub struct TrustProfile {
266    /// TEE vendor identifier (e.g. "intel-tdx", "amd-sev-snp", "aws-nitro").
267    #[serde(default)]
268    pub tee_vendor: String,
269    /// Attestation verification level (e.g. "none", "simulated", "hardware").
270    #[serde(default)]
271    pub attestation_level: String,
272    /// Whether the attestation has been cryptographically verified.
273    #[serde(default)]
274    pub verified: bool,
275}
276
277/// Network topology metadata for a node.
278#[derive(Debug, Clone, Default, Serialize, Deserialize)]
279pub struct NodeNetworkProfile {
280    /// Cloud region or datacenter identifier.
281    #[serde(default)]
282    pub region: String,
283    /// Available upstream bandwidth in Mbps.
284    #[serde(default)]
285    pub bandwidth_mbps: u32,
286    /// Median latency to known peers in milliseconds.
287    #[serde(default)]
288    pub latency_ms_to_peers: u32,
289    /// Whether the node is reachable from the public internet.
290    #[serde(default)]
291    pub is_public: bool,
292}
293
294/// Descriptor for a single downloadable model artifact.
295#[derive(Debug, Clone, Default, Serialize, Deserialize)]
296pub struct ArtifactMetadata {
297    /// Unique artifact identifier.
298    #[serde(default)]
299    pub artifact_id: String,
300    /// Type of this artifact.
301    #[serde(default)]
302    pub artifact_type: ArtifactType,
303    /// Size in bytes.
304    #[serde(default)]
305    pub size_bytes: u64,
306    /// SHA-256 hex digest of the artifact file.
307    #[serde(default)]
308    pub sha256: String,
309    /// Download URL (HTTPS or ipfs://).
310    #[serde(default)]
311    pub url: String,
312    /// Completeness classification of the full artifact set.
313    #[serde(default)]
314    pub completeness: ArtifactCompleteness,
315}
316
317// ---------------------------------------------------------------------------
318// Capability resolver types
319// ---------------------------------------------------------------------------
320
321/// A resolved execution plan for a model inference session.
322#[derive(Debug, Clone, Default, Serialize, Deserialize)]
323pub struct ExecutionPlan {
324    /// Unique plan identifier.
325    pub plan_id: String,
326    /// Model being executed.
327    pub model_id: String,
328    /// Provider peer ID selected for this plan.
329    pub provider_id: String,
330    /// Selected execution mode.
331    pub execution_mode: ExecutionMode,
332    /// Estimated end-to-end latency in milliseconds.
333    #[serde(default)]
334    pub estimated_latency_ms: u32,
335    /// KV-cache profile to use.
336    #[serde(default)]
337    pub kv_profile: KVProfile,
338    /// Placement constraints applied.
339    #[serde(default)]
340    pub constraints: PlacementConstraints,
341    /// Trust profile of the selected provider.
342    #[serde(default)]
343    pub trust_profile: TrustProfile,
344}
345
346/// Receipt emitted after a completed inference session.
347#[derive(Debug, Clone, Default, Serialize, Deserialize)]
348pub struct ExecutionReceipt {
349    /// Unique receipt identifier.
350    pub receipt_id: String,
351    /// Session or request identifier this receipt covers.
352    pub session_id: String,
353    /// Model that was executed.
354    pub model_id: String,
355    /// Provider that served the request.
356    pub provider_id: String,
357    /// Execution mode actually used.
358    pub mode: ExecutionMode,
359    /// Number of prompt tokens processed.
360    #[serde(default)]
361    pub prompt_tokens: u32,
362    /// Number of completion tokens generated.
363    #[serde(default)]
364    pub completion_tokens: u32,
365    /// Number of expert activations (MoE only).
366    #[serde(default)]
367    pub expert_calls: u32,
368    /// Number of layer shard loads (streaming only).
369    #[serde(default)]
370    pub streamed_layer_loads: u32,
371    /// KV-cache profile identifier used.
372    #[serde(default)]
373    pub kv_profile_id: String,
374    /// KV-cache memory resident duration in milliseconds.
375    #[serde(default)]
376    pub kv_memory_ms: u64,
377    /// Whether the session ran in an attested TEE.
378    #[serde(default)]
379    pub attested: bool,
380    /// Reference to the attestation report (if attested).
381    #[serde(default)]
382    pub attestation_ref: String,
383    /// SHA-256 of the raw output bytes.
384    #[serde(default)]
385    pub output_hash: String,
386    /// Unix timestamp (ms) when receipt was created.
387    pub created_unix_ms: i64,
388}
389
390/// Result of capability resolution for a model + client requirements.
391#[derive(Debug, Clone, Default, Serialize, Deserialize)]
392pub struct CapabilityResolution {
393    /// Model being resolved.
394    pub model_id: String,
395    /// Selected provider peer ID.
396    pub resolved_provider: String,
397    /// The execution plan chosen.
398    pub execution_plan: ExecutionPlan,
399    /// Alternative plans (sorted by estimated latency).
400    #[serde(default)]
401    pub alternatives: Vec<ExecutionPlan>,
402}
tenzro_types/runtime.rs

tenzro_types/
runtime.rs
