Skip to main content

stateknot_runtime/
provider_registry.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Frozen exact-version model and tool provider bindings.
5
6use std::{collections::BTreeMap, fmt, sync::Arc};
7
8use stateknot_core::{CapabilityIdentity, ErasedTool, Model, ModelDescriptor, ToolDescriptor};
9use thiserror::Error;
10
11struct ModelProviderBinding {
12    descriptor: ModelDescriptor,
13    provider: Arc<dyn Model>,
14}
15
16/// Startup-only builder for immutable object-safe model provider bindings.
17#[derive(Default)]
18pub struct ModelProviderRegistryBuilder {
19    bindings: BTreeMap<CapabilityIdentity, ModelProviderBinding>,
20}
21
22impl ModelProviderRegistryBuilder {
23    /// Maximum exact model revisions installed in one process snapshot.
24    pub const MAX_BINDINGS: usize = 4096;
25
26    /// Creates an empty model registry builder.
27    #[must_use]
28    pub fn new() -> Self {
29        Self::default()
30    }
31
32    /// Registers one exact provider binding and freezes its descriptor snapshot.
33    ///
34    /// # Errors
35    ///
36    /// Rejects capacity exhaustion or a repeated owner/name/version identity.
37    pub fn register(&mut self, provider: Arc<dyn Model>) -> Result<(), ModelProviderRegistryError> {
38        if self.bindings.len() == Self::MAX_BINDINGS {
39            return Err(ModelProviderRegistryError::TooManyBindings);
40        }
41        let descriptor = provider.descriptor().clone();
42        let identity = descriptor.metadata().identity().clone();
43        if self.bindings.contains_key(&identity) {
44            return Err(ModelProviderRegistryError::DuplicateIdentity {
45                identity: Box::new(identity),
46            });
47        }
48        self.bindings.insert(
49            identity,
50            ModelProviderBinding {
51                descriptor,
52                provider,
53            },
54        );
55        Ok(())
56    }
57
58    /// Freezes this startup snapshot. An empty registry is valid for tool-only workers.
59    #[must_use]
60    pub fn build(self) -> ModelProviderRegistry {
61        ModelProviderRegistry {
62            bindings: Arc::new(self.bindings),
63        }
64    }
65}
66
67impl fmt::Debug for ModelProviderRegistryBuilder {
68    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
69        formatter
70            .debug_struct("ModelProviderRegistryBuilder")
71            .field("bindings", &self.bindings.len())
72            .finish_non_exhaustive()
73    }
74}
75
76/// Immutable exact-version model provider registry.
77///
78/// Lookup starts from the durable descriptor identity, then compares the full
79/// durable descriptor against both the startup snapshot and the provider's
80/// current descriptor reference. Provider aliases, model-family names, and
81/// fallback selection never participate in this recovery boundary.
82#[derive(Clone)]
83pub struct ModelProviderRegistry {
84    bindings: Arc<BTreeMap<CapabilityIdentity, ModelProviderBinding>>,
85}
86
87impl ModelProviderRegistry {
88    /// Resolves and revalidates the exact durable model descriptor.
89    ///
90    /// # Errors
91    ///
92    /// Returns a missing-binding error or fails closed if any descriptor field
93    /// differs from the immutable startup snapshot.
94    pub fn resolve(
95        &self,
96        descriptor: &ModelDescriptor,
97    ) -> Result<Arc<dyn Model>, ModelProviderRegistryError> {
98        let identity = descriptor.metadata().identity();
99        let binding = self.bindings.get(identity).ok_or_else(|| {
100            ModelProviderRegistryError::MissingBinding {
101                identity: Box::new(identity.clone()),
102            }
103        })?;
104        if &binding.descriptor != descriptor || binding.provider.descriptor() != descriptor {
105            return Err(ModelProviderRegistryError::DescriptorMismatch {
106                identity: Box::new(identity.clone()),
107            });
108        }
109        Ok(Arc::clone(&binding.provider))
110    }
111
112    /// Returns the number of exact model revisions.
113    #[must_use]
114    pub fn len(&self) -> usize {
115        self.bindings.len()
116    }
117
118    /// Returns whether this worker has no model bindings.
119    #[must_use]
120    pub fn is_empty(&self) -> bool {
121        self.bindings.is_empty()
122    }
123}
124
125impl fmt::Debug for ModelProviderRegistry {
126    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
127        formatter
128            .debug_struct("ModelProviderRegistry")
129            .field("bindings", &self.bindings.len())
130            .finish_non_exhaustive()
131    }
132}
133
134/// Startup or exact-resolution failure for model providers.
135#[derive(Clone, Debug, Eq, Error, PartialEq)]
136#[non_exhaustive]
137pub enum ModelProviderRegistryError {
138    /// The immutable process binding ceiling was reached.
139    #[error("model provider registry contains too many bindings")]
140    TooManyBindings,
141    /// One exact owner/name/version identity was registered twice.
142    #[error("model provider identity was registered more than once")]
143    DuplicateIdentity {
144        /// Repeated exact binding identity.
145        identity: Box<CapabilityIdentity>,
146    },
147    /// No provider implementation owns the durable identity.
148    #[error("durable model descriptor has no installed provider binding")]
149    MissingBinding {
150        /// Missing exact binding identity.
151        identity: Box<CapabilityIdentity>,
152    },
153    /// Installed descriptor bytes differ from the durable invocation snapshot.
154    #[error("installed model provider descriptor differs from durable snapshot")]
155    DescriptorMismatch {
156        /// Conflicting owner/name/version identity.
157        identity: Box<CapabilityIdentity>,
158    },
159}
160
161struct ToolProviderBinding {
162    descriptor: ToolDescriptor,
163    provider: Arc<dyn ErasedTool>,
164}
165
166/// Startup-only builder for immutable schema-validated tool bindings.
167#[derive(Default)]
168pub struct ToolProviderRegistryBuilder {
169    bindings: BTreeMap<CapabilityIdentity, ToolProviderBinding>,
170}
171
172impl ToolProviderRegistryBuilder {
173    /// Maximum exact tool revisions installed in one process snapshot.
174    pub const MAX_BINDINGS: usize = 16_384;
175
176    /// Creates an empty tool registry builder.
177    #[must_use]
178    pub fn new() -> Self {
179        Self::default()
180    }
181
182    /// Registers one already schema-validated erased tool adapter.
183    ///
184    /// # Errors
185    ///
186    /// Rejects capacity exhaustion or a repeated owner/name/version identity.
187    pub fn register(
188        &mut self,
189        provider: Arc<dyn ErasedTool>,
190    ) -> Result<(), ToolProviderRegistryError> {
191        if self.bindings.len() == Self::MAX_BINDINGS {
192            return Err(ToolProviderRegistryError::TooManyBindings);
193        }
194        let descriptor = provider.descriptor().clone();
195        let identity = descriptor.metadata().identity().clone();
196        if provider.supports_reconciliation() && !descriptor.semantics().supports_status_query() {
197            return Err(
198                ToolProviderRegistryError::ReconciliationCapabilityMismatch {
199                    identity: Box::new(identity),
200                },
201            );
202        }
203        if self.bindings.contains_key(&identity) {
204            return Err(ToolProviderRegistryError::DuplicateIdentity {
205                identity: Box::new(identity),
206            });
207        }
208        self.bindings.insert(
209            identity,
210            ToolProviderBinding {
211                descriptor,
212                provider,
213            },
214        );
215        Ok(())
216    }
217
218    /// Freezes this startup snapshot. An empty registry is valid for model-only workers.
219    #[must_use]
220    pub fn build(self) -> ToolProviderRegistry {
221        ToolProviderRegistry {
222            bindings: Arc::new(self.bindings),
223        }
224    }
225}
226
227impl fmt::Debug for ToolProviderRegistryBuilder {
228    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
229        formatter
230            .debug_struct("ToolProviderRegistryBuilder")
231            .field("bindings", &self.bindings.len())
232            .finish_non_exhaustive()
233    }
234}
235
236/// Immutable exact-version tool provider registry.
237#[derive(Clone)]
238pub struct ToolProviderRegistry {
239    bindings: Arc<BTreeMap<CapabilityIdentity, ToolProviderBinding>>,
240}
241
242impl ToolProviderRegistry {
243    /// Resolves and revalidates the exact durable tool descriptor.
244    ///
245    /// # Errors
246    ///
247    /// Returns a missing-binding error or fails closed if any descriptor field
248    /// differs from the immutable startup snapshot.
249    pub fn resolve(
250        &self,
251        descriptor: &ToolDescriptor,
252    ) -> Result<Arc<dyn ErasedTool>, ToolProviderRegistryError> {
253        let identity = descriptor.metadata().identity();
254        let binding = self.bindings.get(identity).ok_or_else(|| {
255            ToolProviderRegistryError::MissingBinding {
256                identity: Box::new(identity.clone()),
257            }
258        })?;
259        if &binding.descriptor != descriptor || binding.provider.descriptor() != descriptor {
260            return Err(ToolProviderRegistryError::DescriptorMismatch {
261                identity: Box::new(identity.clone()),
262            });
263        }
264        Ok(Arc::clone(&binding.provider))
265    }
266
267    /// Returns the number of exact tool revisions.
268    #[must_use]
269    pub fn len(&self) -> usize {
270        self.bindings.len()
271    }
272
273    /// Returns whether this worker has no tool bindings.
274    #[must_use]
275    pub fn is_empty(&self) -> bool {
276        self.bindings.is_empty()
277    }
278}
279
280impl fmt::Debug for ToolProviderRegistry {
281    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
282        formatter
283            .debug_struct("ToolProviderRegistry")
284            .field("bindings", &self.bindings.len())
285            .finish_non_exhaustive()
286    }
287}
288
289/// Startup or exact-resolution failure for tool adapters.
290#[derive(Clone, Debug, Eq, Error, PartialEq)]
291#[non_exhaustive]
292pub enum ToolProviderRegistryError {
293    /// The immutable process binding ceiling was reached.
294    #[error("tool provider registry contains too many bindings")]
295    TooManyBindings,
296    /// One exact owner/name/version identity was registered twice.
297    #[error("tool provider identity was registered more than once")]
298    DuplicateIdentity {
299        /// Repeated exact binding identity.
300        identity: Box<CapabilityIdentity>,
301    },
302    /// No executable adapter owns the durable identity.
303    #[error("durable tool descriptor has no installed provider binding")]
304    MissingBinding {
305        /// Missing exact binding identity.
306        identity: Box<CapabilityIdentity>,
307    },
308    /// Installed descriptor bytes differ from the durable invocation snapshot.
309    #[error("installed tool provider descriptor differs from durable snapshot")]
310    DescriptorMismatch {
311        /// Conflicting owner/name/version identity.
312        identity: Box<CapabilityIdentity>,
313    },
314    /// Descriptor status-query semantics and executable provider capability differ.
315    #[error("tool reconciliation capability differs from its descriptor declaration")]
316    ReconciliationCapabilityMismatch {
317        /// Rejected exact binding identity.
318        identity: Box<CapabilityIdentity>,
319    },
320}
321
322#[cfg(test)]
323mod tests {
324    use stateknot_core::{
325        BoxFuture, BoxStream, ModelContext, ModelError, ModelEvent, ModelRequest, ModelResponse,
326        ToolContext, ToolError, ToolInput, ToolResult,
327    };
328
329    use super::*;
330
331    struct TestModel {
332        descriptor: ModelDescriptor,
333    }
334
335    impl Model for TestModel {
336        fn descriptor(&self) -> &ModelDescriptor {
337            &self.descriptor
338        }
339
340        fn invoke(
341            &self,
342            _: ModelContext,
343            _: ModelRequest,
344        ) -> BoxFuture<'_, Result<ModelResponse, ModelError>> {
345            unimplemented!("provider registry tests never dispatch")
346        }
347
348        fn stream(
349            &self,
350            _: ModelContext,
351            _: ModelRequest,
352        ) -> BoxStream<'_, Result<ModelEvent, ModelError>> {
353            unimplemented!("provider registry tests never dispatch")
354        }
355    }
356
357    struct TestTool {
358        descriptor: ToolDescriptor,
359    }
360
361    impl ErasedTool for TestTool {
362        fn descriptor(&self) -> &ToolDescriptor {
363            &self.descriptor
364        }
365
366        fn supports_reconciliation(&self) -> bool {
367            true
368        }
369
370        fn call(
371            &self,
372            _: ToolContext,
373            _: ToolInput,
374        ) -> BoxFuture<'_, Result<ToolResult, ToolError>> {
375            unimplemented!("provider registry tests never dispatch")
376        }
377    }
378
379    fn model_descriptor(name: &str) -> ModelDescriptor {
380        let fixture: serde_json::Value = serde_json::from_str(include_str!(
381            "../../stateknot-core/tests/fixtures/core-model-descriptor-v1.json"
382        ))
383        .unwrap();
384        let mut descriptor = fixture["descriptors"]["valid"][0].clone();
385        descriptor["metadata"]["identity"]["capability"]["name"] =
386            serde_json::Value::String(name.to_owned());
387        serde_json::from_value(descriptor).unwrap()
388    }
389
390    fn tool_descriptor(name: &str) -> ToolDescriptor {
391        let fixture: serde_json::Value = serde_json::from_str(include_str!(
392            "../../stateknot-core/tests/fixtures/core-tool-v1.json"
393        ))
394        .unwrap();
395        let mut descriptor = fixture["descriptors"]["valid"][0].clone();
396        descriptor["metadata"]["identity"]["capability"]["name"] =
397            serde_json::Value::String(name.to_owned());
398        serde_json::from_value(descriptor).unwrap()
399    }
400
401    fn tool_descriptor_without_status_query(name: &str) -> ToolDescriptor {
402        let mut descriptor = serde_json::to_value(tool_descriptor(name)).unwrap();
403        descriptor["semantics"]["status_query"] = serde_json::Value::Bool(false);
404        serde_json::from_value(descriptor).unwrap()
405    }
406
407    #[test]
408    fn model_registry_rejects_duplicates_and_descriptor_substitution() {
409        let primary = model_descriptor("models.primary");
410        let alternate = model_descriptor("models.alternate");
411        let mut builder = ModelProviderRegistryBuilder::new();
412        builder
413            .register(Arc::new(TestModel {
414                descriptor: primary.clone(),
415            }))
416            .unwrap();
417        assert!(matches!(
418            builder.register(Arc::new(TestModel {
419                descriptor: primary.clone()
420            })),
421            Err(ModelProviderRegistryError::DuplicateIdentity { .. })
422        ));
423        let registry = builder.build();
424        assert!(registry.resolve(&primary).is_ok());
425        assert!(matches!(
426            registry.resolve(&alternate),
427            Err(ModelProviderRegistryError::MissingBinding { .. })
428        ));
429    }
430
431    #[test]
432    fn tool_registry_rejects_duplicates_and_missing_exact_versions() {
433        let primary = tool_descriptor("payments.capture");
434        let alternate = tool_descriptor("payments.refund");
435        let mut builder = ToolProviderRegistryBuilder::new();
436        builder
437            .register(Arc::new(TestTool {
438                descriptor: primary.clone(),
439            }))
440            .unwrap();
441        assert!(matches!(
442            builder.register(Arc::new(TestTool {
443                descriptor: primary.clone()
444            })),
445            Err(ToolProviderRegistryError::DuplicateIdentity { .. })
446        ));
447        let registry = builder.build();
448        assert!(registry.resolve(&primary).is_ok());
449        assert!(matches!(
450            registry.resolve(&alternate),
451            Err(ToolProviderRegistryError::MissingBinding { .. })
452        ));
453    }
454
455    #[test]
456    fn tool_registry_rejects_undeclared_reconciliation_implementations() {
457        let mut builder = ToolProviderRegistryBuilder::new();
458        assert!(matches!(
459            builder.register(Arc::new(TestTool {
460                descriptor: tool_descriptor_without_status_query("payments.unreconciled"),
461            })),
462            Err(ToolProviderRegistryError::ReconciliationCapabilityMismatch { .. })
463        ));
464    }
465}