1use 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#[derive(Default)]
18pub struct ModelProviderRegistryBuilder {
19 bindings: BTreeMap<CapabilityIdentity, ModelProviderBinding>,
20}
21
22impl ModelProviderRegistryBuilder {
23 pub const MAX_BINDINGS: usize = 4096;
25
26 #[must_use]
28 pub fn new() -> Self {
29 Self::default()
30 }
31
32 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 #[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#[derive(Clone)]
83pub struct ModelProviderRegistry {
84 bindings: Arc<BTreeMap<CapabilityIdentity, ModelProviderBinding>>,
85}
86
87impl ModelProviderRegistry {
88 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 #[must_use]
114 pub fn len(&self) -> usize {
115 self.bindings.len()
116 }
117
118 #[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#[derive(Clone, Debug, Eq, Error, PartialEq)]
136#[non_exhaustive]
137pub enum ModelProviderRegistryError {
138 #[error("model provider registry contains too many bindings")]
140 TooManyBindings,
141 #[error("model provider identity was registered more than once")]
143 DuplicateIdentity {
144 identity: Box<CapabilityIdentity>,
146 },
147 #[error("durable model descriptor has no installed provider binding")]
149 MissingBinding {
150 identity: Box<CapabilityIdentity>,
152 },
153 #[error("installed model provider descriptor differs from durable snapshot")]
155 DescriptorMismatch {
156 identity: Box<CapabilityIdentity>,
158 },
159}
160
161struct ToolProviderBinding {
162 descriptor: ToolDescriptor,
163 provider: Arc<dyn ErasedTool>,
164}
165
166#[derive(Default)]
168pub struct ToolProviderRegistryBuilder {
169 bindings: BTreeMap<CapabilityIdentity, ToolProviderBinding>,
170}
171
172impl ToolProviderRegistryBuilder {
173 pub const MAX_BINDINGS: usize = 16_384;
175
176 #[must_use]
178 pub fn new() -> Self {
179 Self::default()
180 }
181
182 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 #[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#[derive(Clone)]
238pub struct ToolProviderRegistry {
239 bindings: Arc<BTreeMap<CapabilityIdentity, ToolProviderBinding>>,
240}
241
242impl ToolProviderRegistry {
243 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 #[must_use]
269 pub fn len(&self) -> usize {
270 self.bindings.len()
271 }
272
273 #[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#[derive(Clone, Debug, Eq, Error, PartialEq)]
291#[non_exhaustive]
292pub enum ToolProviderRegistryError {
293 #[error("tool provider registry contains too many bindings")]
295 TooManyBindings,
296 #[error("tool provider identity was registered more than once")]
298 DuplicateIdentity {
299 identity: Box<CapabilityIdentity>,
301 },
302 #[error("durable tool descriptor has no installed provider binding")]
304 MissingBinding {
305 identity: Box<CapabilityIdentity>,
307 },
308 #[error("installed tool provider descriptor differs from durable snapshot")]
310 DescriptorMismatch {
311 identity: Box<CapabilityIdentity>,
313 },
314 #[error("tool reconciliation capability differs from its descriptor declaration")]
316 ReconciliationCapabilityMismatch {
317 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}