Skip to main content

ml_runtime_model/
lib.rs

1use async_trait::async_trait;
2use serde::{Deserialize, Serialize};
3use sha2::{Digest, Sha256};
4use std::{
5    any::Any,
6    collections::BTreeMap,
7    fs,
8    io::{Read, Write},
9    path::{Path, PathBuf},
10    sync::Arc,
11};
12use tokio_util::sync::CancellationToken;
13
14pub type ModelMetadata = BTreeMap<String, String>;
15
16/// A validated, stable model name and version used by catalogs and installers.
17#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, Ord, PartialOrd)]
18pub struct ModelId {
19    pub name: String,
20    pub version: String,
21}
22
23impl ModelId {
24    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Result<Self, CatalogError> {
25        let id = Self {
26            name: name.into(),
27            version: version.into(),
28        };
29        id.validate()?;
30        Ok(id)
31    }
32
33    pub fn parse(reference: &str) -> Result<Self, CatalogError> {
34        let (name, version) = reference
35            .rsplit_once('@')
36            .ok_or_else(|| CatalogError::InvalidIdentity(reference.to_owned()))?;
37        Self::new(name, version)
38    }
39
40    pub fn validate(&self) -> Result<(), CatalogError> {
41        if self.name.is_empty()
42            || self.version.is_empty()
43            || self.name.contains(['/', '\\', '@'])
44            || self.version.contains(['/', '\\', '@'])
45            || self.name.contains("..")
46            || self.version.contains("..")
47        {
48            return Err(CatalogError::InvalidIdentity(format!(
49                "{}@{}",
50                self.name, self.version
51            )));
52        }
53        Ok(())
54    }
55}
56
57impl std::fmt::Display for ModelId {
58    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
59        write!(f, "{}@{}", self.name, self.version)
60    }
61}
62
63#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
64pub enum ModelFormat {
65    #[serde(rename = "onnx", alias = "Onnx")]
66    Onnx,
67    #[serde(rename = "coreml", alias = "CoreMl")]
68    CoreMl,
69    #[serde(rename = "gguf", alias = "Gguf")]
70    Gguf,
71    #[serde(rename = "safetensors", alias = "Safetensors")]
72    Safetensors,
73    #[serde(rename = "tensorrt", alias = "TensorRt")]
74    TensorRt,
75    #[serde(rename = "unknown", alias = "Unknown")]
76    Unknown,
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
80pub enum ModelLocation {
81    Path(String),
82    Uri(String),
83    Embedded(String),
84    Memory,
85}
86
87/// An explicit backend-independent model definition and artifact location.
88#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
89pub struct ModelSpec {
90    pub id: String,
91    pub version: Option<String>,
92    pub format: ModelFormat,
93    pub location: ModelLocation,
94    pub metadata: ModelMetadata,
95}
96
97#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
98pub struct ModelManifest {
99    #[serde(default = "default_schema_version")]
100    pub schema_version: u32,
101    #[serde(alias = "name")]
102    pub id: String,
103    #[serde(default)]
104    pub model_version: Option<String>,
105    #[serde(default)]
106    pub version: Option<String>,
107    pub format: ModelFormat,
108    #[serde(alias = "artifact_path")]
109    pub artifact: ArtifactSpec,
110    #[serde(default)]
111    pub metadata: ModelMetadata,
112    #[serde(default)]
113    pub inputs: Vec<ModelTensorSpec>,
114    #[serde(default)]
115    pub outputs: Vec<ModelTensorSpec>,
116}
117
118#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
119pub struct ArtifactSpec {
120    pub path: String,
121    #[serde(default)]
122    pub size_bytes: Option<u64>,
123    #[serde(default)]
124    pub sha256: Option<String>,
125}
126
127impl<'de> Deserialize<'de> for ArtifactSpec {
128    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
129    where
130        D: serde::Deserializer<'de>,
131    {
132        #[derive(Deserialize)]
133        #[serde(untagged)]
134        enum Input {
135            Path(String),
136            Metadata {
137                path: String,
138                #[serde(default)]
139                size_bytes: Option<u64>,
140                #[serde(default)]
141                sha256: Option<String>,
142            },
143        }
144        match Input::deserialize(deserializer)? {
145            Input::Path(path) => Ok(Self {
146                path,
147                size_bytes: None,
148                sha256: None,
149            }),
150            Input::Metadata {
151                path,
152                size_bytes,
153                sha256,
154            } => Ok(Self {
155                path,
156                size_bytes,
157                sha256,
158            }),
159        }
160    }
161}
162
163#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
164pub struct ModelTensorSpec {
165    pub name: String,
166    #[serde(default)]
167    pub data_type: Option<String>,
168    #[serde(default)]
169    pub shape: Option<Vec<i64>>,
170}
171
172fn default_schema_version() -> u32 {
173    1
174}
175
176#[derive(Clone, Debug, PartialEq, Eq)]
177pub struct ModelPackage {
178    pub manifest: ModelManifest,
179    pub root: PathBuf,
180    pub artifact: PathBuf,
181}
182
183impl ModelPackage {
184    pub fn open(root: impl AsRef<Path>) -> Result<Self, String> {
185        let root = root.as_ref().to_path_buf();
186        let manifest_path = root.join("manifest.json");
187        let manifest: ModelManifest = serde_json::from_slice(
188            &fs::read(&manifest_path)
189                .map_err(|error| format!("read {}: {error}", manifest_path.display()))?,
190        )
191        .map_err(|error| format!("parse {}: {error}", manifest_path.display()))?;
192        if manifest.schema_version != 1 {
193            return Err(format!(
194                "unsupported model manifest schema version {}",
195                manifest.schema_version
196            ));
197        }
198        let artifact_name = manifest.artifact.path.as_str();
199        if artifact_name.is_empty() {
200            return Err("model artifact path is empty".to_owned());
201        }
202        let artifact_path = Path::new(artifact_name);
203        if artifact_path.is_absolute()
204            || artifact_path
205                .components()
206                .any(|component| matches!(component, std::path::Component::ParentDir))
207        {
208            return Err("model artifact path must stay inside the model package".to_owned());
209        }
210        let artifact = root.join(artifact_name);
211        let canonical_root = root
212            .canonicalize()
213            .map_err(|error| format!("resolve model package: {error}"))?;
214        let canonical_artifact = artifact
215            .canonicalize()
216            .map_err(|error| format!("resolve model artifact: {error}"))?;
217        if canonical_artifact.strip_prefix(&canonical_root).is_err() {
218            return Err("model artifact must be inside the model package".to_owned());
219        }
220
221        if !artifact.is_file() && !artifact.is_dir() {
222            return Err(format!(
223                "model artifact does not exist: {}",
224                artifact.display()
225            ));
226        }
227        Self::reject_symlinks(&artifact)
228            .map_err(|reason| format!("model artifact is unsafe: {reason}"))?;
229        Ok(Self {
230            manifest,
231            root,
232            artifact,
233        })
234    }
235
236    fn reject_symlinks(path: &Path) -> Result<(), String> {
237        let metadata = fs::symlink_metadata(path).map_err(|error| error.to_string())?;
238        if metadata.file_type().is_symlink() {
239            return Err("symbolic links are not allowed".to_owned());
240        }
241        if metadata.is_dir() {
242            for entry in fs::read_dir(path).map_err(|error| error.to_string())? {
243                Self::reject_symlinks(&entry.map_err(|error| error.to_string())?.path())?;
244            }
245        }
246        Ok(())
247    }
248
249    pub fn spec(&self) -> ModelSpec {
250        ModelSpec {
251            id: self.manifest.id.clone(),
252            version: self
253                .manifest
254                .model_version
255                .clone()
256                .or_else(|| self.manifest.version.clone()),
257            format: self.manifest.format.clone(),
258            location: ModelLocation::Path(self.artifact.display().to_string()),
259            metadata: self.manifest.metadata.clone(),
260        }
261    }
262
263    pub fn validate_artifact(&self) -> Result<(), CatalogError> {
264        if let Some(expected) = self.manifest.artifact.size_bytes {
265            let actual = artifact_size(&self.artifact)?;
266            if actual != expected {
267                return Err(CatalogError::ArtifactIntegrity {
268                    model: self.manifest.id.clone(),
269                    reason: format!("size mismatch: expected {expected}, got {actual}"),
270                });
271            }
272        }
273        if let Some(expected) = self.manifest.artifact.sha256.as_deref() {
274            let actual = sha256(&self.artifact)?;
275            if !expected.eq_ignore_ascii_case(&actual) {
276                return Err(CatalogError::ArtifactIntegrity {
277                    model: self.manifest.id.clone(),
278                    reason: format!("sha256 mismatch: expected {expected}, got {actual}"),
279                });
280            }
281        }
282        Ok(())
283    }
284}
285
286impl ModelSpec {
287    pub fn new(id: impl Into<String>, format: ModelFormat, location: ModelLocation) -> Self {
288        Self {
289            id: id.into(),
290            version: None,
291            format,
292            location,
293            metadata: ModelMetadata::new(),
294        }
295    }
296}
297
298fn artifact_size(path: &Path) -> Result<u64, CatalogError> {
299    if path.is_file() {
300        return Ok(fs::metadata(path)
301            .map_err(|error| CatalogError::Io(error.to_string()))?
302            .len());
303    }
304    let mut total = 0;
305    for entry in fs::read_dir(path).map_err(|error| CatalogError::Io(error.to_string()))? {
306        total += artifact_size(
307            &entry
308                .map_err(|error| CatalogError::Io(error.to_string()))?
309                .path(),
310        )?;
311    }
312    Ok(total)
313}
314
315fn sha256(path: &Path) -> Result<String, CatalogError> {
316    let mut digest = Sha256::new();
317    if path.is_file() {
318        digest.update(fs::read(path).map_err(|error| CatalogError::Io(error.to_string()))?);
319    } else {
320        let mut entries = fs::read_dir(path)
321            .map_err(|error| CatalogError::Io(error.to_string()))?
322            .collect::<Result<Vec<_>, _>>()
323            .map_err(|error| CatalogError::Io(error.to_string()))?;
324        entries.sort_by_key(|entry| entry.path());
325        for entry in entries {
326            digest.update(sha256(&entry.path())?.as_bytes());
327        }
328    }
329    Ok(format!("{:x}", digest.finalize()))
330}
331
332/// Catalog discovery information. A descriptor is metadata, not a loaded resource.
333#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
334pub struct ModelDescriptor {
335    pub id: ModelId,
336    pub format: ModelFormat,
337    pub package_path: PathBuf,
338    pub manifest: ModelManifest,
339}
340
341impl ModelDescriptor {
342    pub fn spec(&self) -> ModelSpec {
343        ModelPackage {
344            manifest: self.manifest.clone(),
345            root: self.package_path.clone(),
346            artifact: self.package_path.join(&self.manifest.artifact.path),
347        }
348        .spec()
349    }
350}
351
352#[derive(Clone, Debug, PartialEq, Eq)]
353pub enum CatalogError {
354    Io(String),
355    InvalidIdentity(String),
356    InvalidPackage { path: PathBuf, reason: String },
357    ModelNotFound(String),
358    AmbiguousModel(String),
359    DuplicateIdentity(ModelId),
360    ArtifactIntegrity { model: String, reason: String },
361}
362
363impl std::fmt::Display for CatalogError {
364    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
365        match self {
366            Self::Io(reason) => write!(f, "catalog unavailable: {reason}"),
367            Self::InvalidIdentity(identity) => write!(f, "invalid model identity: {identity}"),
368            Self::InvalidPackage { path, reason } => {
369                write!(f, "invalid model package {}: {reason}", path.display())
370            }
371            Self::ModelNotFound(model) => write!(f, "model not found: {model}"),
372            Self::AmbiguousModel(model) => write!(f, "ambiguous model: {model}"),
373            Self::DuplicateIdentity(id) => write!(f, "duplicate model identity: {id}"),
374            Self::ArtifactIntegrity { model, reason } => {
375                write!(f, "artifact integrity failure for {model}: {reason}")
376            }
377        }
378    }
379}
380
381impl std::error::Error for CatalogError {}
382
383#[async_trait]
384pub trait ModelCatalog: Send + Sync {
385    async fn list(&self) -> Result<Vec<ModelDescriptor>, CatalogError>;
386    async fn resolve(&self, reference: &ModelReference) -> Result<ModelDescriptor, CatalogError>;
387    async fn validate(&self, id: &ModelId) -> Result<(), CatalogError>;
388    async fn refresh(&self) -> Result<(), CatalogError>;
389}
390
391#[derive(Clone, Debug)]
392pub struct FilesystemModelCatalog {
393    roots: Vec<PathBuf>,
394}
395
396impl FilesystemModelCatalog {
397    pub fn new(root: impl Into<PathBuf>) -> Self {
398        Self {
399            roots: vec![root.into()],
400        }
401    }
402
403    pub fn from_roots(roots: impl IntoIterator<Item = PathBuf>) -> Self {
404        Self {
405            roots: roots.into_iter().collect(),
406        }
407    }
408
409    pub fn roots(&self) -> &[PathBuf] {
410        &self.roots
411    }
412
413    fn discover(&self) -> Result<Vec<ModelDescriptor>, CatalogError> {
414        let mut packages = Vec::new();
415        for root in &self.roots {
416            discover_dirs(root, &mut packages)?;
417        }
418        packages.sort_by_key(|descriptor| {
419            (
420                descriptor.id.name.clone(),
421                descriptor.id.version.clone(),
422                format!("{:?}", descriptor.format),
423                descriptor.package_path.clone(),
424            )
425        });
426        for pair in packages.windows(2) {
427            if pair[0].id == pair[1].id {
428                return Err(CatalogError::DuplicateIdentity(pair[0].id.clone()));
429            }
430        }
431        Ok(packages)
432    }
433}
434
435fn discover_dirs(path: &Path, packages: &mut Vec<ModelDescriptor>) -> Result<(), CatalogError> {
436    if !path.is_dir() {
437        return Err(CatalogError::Io(format!(
438            "root is not a directory: {}",
439            path.display()
440        )));
441    }
442    if path.join("manifest.json").is_file() {
443        let package = ModelPackage::open(path).map_err(|reason| CatalogError::InvalidPackage {
444            path: path.to_path_buf(),
445            reason,
446        })?;
447        let version = package
448            .manifest
449            .model_version
450            .clone()
451            .or_else(|| package.manifest.version.clone())
452            .ok_or_else(|| CatalogError::InvalidPackage {
453                path: path.to_path_buf(),
454                reason: "model version is required".to_owned(),
455            })?;
456        let id = ModelId::new(package.manifest.id.clone(), version)?;
457        packages.push(ModelDescriptor {
458            id,
459            format: package.manifest.format.clone(),
460            package_path: path.to_path_buf(),
461            manifest: package.manifest,
462        });
463        return Ok(());
464    }
465    let mut entries = fs::read_dir(path)
466        .map_err(|error| CatalogError::Io(format!("read {}: {error}", path.display())))?
467        .collect::<Result<Vec<_>, _>>()
468        .map_err(|error| CatalogError::Io(error.to_string()))?;
469    entries.sort_by_key(|entry| entry.path());
470    for entry in entries {
471        if entry
472            .file_type()
473            .map_err(|error| CatalogError::Io(error.to_string()))?
474            .is_dir()
475        {
476            discover_dirs(&entry.path(), packages)?;
477        }
478    }
479    Ok(())
480}
481
482#[async_trait]
483impl ModelCatalog for FilesystemModelCatalog {
484    async fn list(&self) -> Result<Vec<ModelDescriptor>, CatalogError> {
485        self.discover()
486    }
487
488    async fn resolve(&self, reference: &ModelReference) -> Result<ModelDescriptor, CatalogError> {
489        let (name, version) = match reference {
490            ModelReference::Id { id, version } => (id.as_str(), version.as_deref()),
491            ModelReference::Spec(spec) => {
492                return Err(CatalogError::InvalidIdentity(spec.id.clone()))
493            }
494        };
495        if name.is_empty() || name.contains(['/', '\\', '@']) || name.contains("..") {
496            return Err(CatalogError::InvalidIdentity(name.to_owned()));
497        }
498        let matches = self
499            .discover()?
500            .into_iter()
501            .filter(|descriptor| {
502                descriptor.id.name == name
503                    && version.is_none_or(|version| descriptor.id.version == version)
504            })
505            .collect::<Vec<_>>();
506        match matches.as_slice() {
507            [] => Err(CatalogError::ModelNotFound(match version {
508                Some(version) => format!("{name}@{version}"),
509                None => name.to_owned(),
510            })),
511            [descriptor] => Ok(descriptor.clone()),
512            _ => Err(CatalogError::AmbiguousModel(name.to_owned())),
513        }
514    }
515
516    async fn validate(&self, id: &ModelId) -> Result<(), CatalogError> {
517        let descriptor = self
518            .discover()?
519            .into_iter()
520            .find(|descriptor| descriptor.id == *id)
521            .ok_or_else(|| CatalogError::ModelNotFound(id.to_string()))?;
522        ModelPackage::open(&descriptor.package_path)
523            .map_err(|reason| CatalogError::InvalidPackage {
524                path: descriptor.package_path.clone(),
525                reason,
526            })?
527            .validate_artifact()
528    }
529
530    async fn refresh(&self) -> Result<(), CatalogError> {
531        self.discover().map(|_| ())
532    }
533}
534
535/// A request-time model reference: either a catalog identity or an explicit specification.
536#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
537pub enum ModelReference {
538    Id { id: String, version: Option<String> },
539    Spec(ModelSpec),
540}
541
542impl ModelReference {
543    pub fn id(id: impl Into<String>, version: Option<String>) -> Self {
544        Self::Id {
545            id: id.into(),
546            version,
547        }
548    }
549
550    pub fn versioned(id: impl Into<String>, version: impl Into<String>) -> Self {
551        Self::id(id, Some(version.into()))
552    }
553
554    pub fn latest(id: impl Into<String>) -> Self {
555        Self::id(id, None)
556    }
557}
558
559impl From<ModelSpec> for ModelReference {
560    fn from(value: ModelSpec) -> Self {
561        Self::Spec(value)
562    }
563}
564
565#[derive(Clone, Debug, PartialEq, Eq)]
566pub struct ModelFetchRequest {
567    pub model: ModelId,
568    pub source: ModelSourceReference,
569}
570
571#[derive(Clone, Debug, PartialEq, Eq)]
572pub enum ModelSourceReference {
573    Path(PathBuf),
574    Uri(String),
575}
576
577#[derive(Clone, Debug)]
578pub struct AcquisitionConfig {
579    pub max_download_bytes: u64,
580    pub timeout_secs: u64,
581}
582
583impl Default for AcquisitionConfig {
584    fn default() -> Self {
585        Self {
586            max_download_bytes: 4 * 1024 * 1024 * 1024,
587            timeout_secs: 300,
588        }
589    }
590}
591
592#[derive(Clone, Debug, PartialEq, Eq)]
593pub struct ModelArtifact {
594    pub package_path: PathBuf,
595    pub bytes: u64,
596    pub sha256: String,
597}
598
599#[derive(Clone, Debug, PartialEq, Eq)]
600pub enum InstallMode {
601    KeepExisting,
602    Replace,
603}
604
605#[derive(Clone, Debug, PartialEq, Eq)]
606pub enum InstallResult {
607    Installed(ModelDescriptor),
608    AlreadyInstalled(ModelDescriptor),
609}
610
611#[derive(Clone, Debug, PartialEq, Eq)]
612pub enum AcquisitionError {
613    Io(String),
614    InvalidRequest(String),
615    Cancelled,
616    LimitExceeded { limit: u64, actual: u64 },
617    InvalidPackage { path: PathBuf, reason: String },
618    IdentityMismatch { requested: ModelId, found: ModelId },
619    AlreadyInstalled(ModelId),
620    Catalog(CatalogError),
621}
622
623impl std::fmt::Display for AcquisitionError {
624    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
625        match self {
626            Self::Io(reason) => write!(f, "acquisition I/O error: {reason}"),
627            Self::InvalidRequest(reason) => write!(f, "invalid acquisition request: {reason}"),
628            Self::Cancelled => write!(f, "model acquisition cancelled"),
629            Self::LimitExceeded { limit, actual } => {
630                write!(f, "model acquisition exceeds {limit} bytes (got {actual})")
631            }
632            Self::InvalidPackage { path, reason } => {
633                write!(f, "invalid model package {}: {reason}", path.display())
634            }
635            Self::IdentityMismatch { requested, found } => {
636                write!(f, "requested model {requested}, package contains {found}")
637            }
638            Self::AlreadyInstalled(id) => write!(f, "model already installed: {id}"),
639            Self::Catalog(error) => error.fmt(f),
640        }
641    }
642}
643
644impl std::error::Error for AcquisitionError {}
645
646#[async_trait]
647pub trait ModelSource: Send + Sync {
648    async fn fetch(
649        &self,
650        request: &ModelFetchRequest,
651        destination: &Path,
652        config: &AcquisitionConfig,
653        cancellation: Option<&CancellationToken>,
654    ) -> Result<ModelArtifact, AcquisitionError>;
655}
656
657#[derive(Clone, Debug, Default)]
658pub struct FileModelSource;
659
660impl FileModelSource {
661    pub fn new() -> Self {
662        Self
663    }
664}
665
666#[async_trait]
667impl ModelSource for FileModelSource {
668    async fn fetch(
669        &self,
670        request: &ModelFetchRequest,
671        destination: &Path,
672        config: &AcquisitionConfig,
673        cancellation: Option<&CancellationToken>,
674    ) -> Result<ModelArtifact, AcquisitionError> {
675        let source = match &request.source {
676            ModelSourceReference::Path(path) => path,
677            ModelSourceReference::Uri(_) => {
678                return Err(AcquisitionError::InvalidRequest(
679                    "file source requires a filesystem path".to_owned(),
680                ))
681            }
682        };
683        if !source.is_dir() {
684            return Err(AcquisitionError::InvalidRequest(format!(
685                "model source is not a package directory: {}",
686                source.display()
687            )));
688        }
689        copy_package(source, destination, config.max_download_bytes, cancellation)?;
690        let package =
691            ModelPackage::open(destination).map_err(|reason| AcquisitionError::InvalidPackage {
692                path: destination.to_path_buf(),
693                reason,
694            })?;
695        package
696            .validate_artifact()
697            .map_err(AcquisitionError::Catalog)?;
698        let id = package_id(&package)?;
699        if id != request.model {
700            return Err(AcquisitionError::IdentityMismatch {
701                requested: request.model.clone(),
702                found: id,
703            });
704        }
705        Ok(ModelArtifact {
706            package_path: destination.to_path_buf(),
707            bytes: artifact_size(&package.artifact).map_err(|error| match error {
708                CatalogError::Io(reason) => AcquisitionError::Io(reason),
709                other => AcquisitionError::Catalog(other),
710            })?,
711            sha256: sha256(&package.artifact).map_err(|error| match error {
712                CatalogError::Io(reason) => AcquisitionError::Io(reason),
713                other => AcquisitionError::Catalog(other),
714            })?,
715        })
716    }
717}
718
719#[derive(Clone, Debug)]
720pub struct HttpModelSource {
721    client: reqwest::Client,
722    allow_insecure_http: bool,
723}
724
725impl HttpModelSource {
726    pub fn new() -> Result<Self, AcquisitionError> {
727        let client = reqwest::Client::builder()
728            .redirect(reqwest::redirect::Policy::limited(5))
729            .build()
730            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
731        Ok(Self {
732            client,
733            allow_insecure_http: false,
734        })
735    }
736
737    pub fn allow_insecure_http(mut self, allow: bool) -> Self {
738        self.allow_insecure_http = allow;
739        self
740    }
741}
742
743#[async_trait]
744impl ModelSource for HttpModelSource {
745    async fn fetch(
746        &self,
747        request: &ModelFetchRequest,
748        destination: &Path,
749        config: &AcquisitionConfig,
750        cancellation: Option<&CancellationToken>,
751    ) -> Result<ModelArtifact, AcquisitionError> {
752        let base = match &request.source {
753            ModelSourceReference::Uri(uri) => uri.trim_end_matches('/').to_owned(),
754            ModelSourceReference::Path(_) => {
755                return Err(AcquisitionError::InvalidRequest(
756                    "HTTP source requires a URI".to_owned(),
757                ))
758            }
759        };
760        let manifest_url = if base.ends_with("manifest.json") {
761            base
762        } else {
763            format!("{base}/manifest.json")
764        };
765        validate_http_uri(&manifest_url, self.allow_insecure_http)?;
766        let response = tokio::time::timeout(
767            std::time::Duration::from_secs(config.timeout_secs),
768            self.client.get(&manifest_url).send(),
769        )
770        .await
771        .map_err(|_| AcquisitionError::Io("manifest request timed out".to_owned()))?
772        .map_err(|error| AcquisitionError::Io(error.to_string()))?
773        .error_for_status()
774        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
775        let manifest: ModelManifest =
776            response
777                .json()
778                .await
779                .map_err(|error| AcquisitionError::InvalidPackage {
780                    path: destination.to_path_buf(),
781                    reason: error.to_string(),
782                })?;
783        let version = manifest
784            .model_version
785            .clone()
786            .or_else(|| manifest.version.clone())
787            .ok_or_else(|| AcquisitionError::InvalidPackage {
788                path: destination.to_path_buf(),
789                reason: "model version is required".to_owned(),
790            })?;
791        let found =
792            ModelId::new(manifest.id.clone(), version).map_err(AcquisitionError::Catalog)?;
793        if found != request.model {
794            return Err(AcquisitionError::IdentityMismatch {
795                requested: request.model.clone(),
796                found,
797            });
798        }
799        let artifact_path = Path::new(&manifest.artifact.path);
800        if artifact_path.is_absolute()
801            || artifact_path
802                .components()
803                .any(|component| matches!(component, std::path::Component::ParentDir))
804        {
805            return Err(AcquisitionError::InvalidPackage {
806                path: destination.to_path_buf(),
807                reason: "artifact path must stay inside the package".to_owned(),
808            });
809        }
810        let artifact_url = format!(
811            "{}/{}",
812            manifest_url
813                .trim_end_matches("manifest.json")
814                .trim_end_matches('/'),
815            manifest.artifact.path
816        );
817        validate_http_uri(&artifact_url, self.allow_insecure_http)?;
818        let response = self
819            .client
820            .get(artifact_url)
821            .send()
822            .await
823            .map_err(|error| AcquisitionError::Io(error.to_string()))?
824            .error_for_status()
825            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
826        if response
827            .content_length()
828            .is_some_and(|size| size > config.max_download_bytes)
829        {
830            return Err(AcquisitionError::LimitExceeded {
831                limit: config.max_download_bytes,
832                actual: response.content_length().unwrap_or_default(),
833            });
834        }
835        fs::create_dir_all(
836            destination.join(artifact_path.parent().unwrap_or_else(|| Path::new(""))),
837        )
838        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
839        fs::write(
840            destination.join(artifact_path),
841            download_body(response, config, cancellation).await?,
842        )
843        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
844        fs::write(
845            destination.join("manifest.json"),
846            serde_json::to_vec(&manifest).map_err(|error| AcquisitionError::InvalidPackage {
847                path: destination.to_path_buf(),
848                reason: error.to_string(),
849            })?,
850        )
851        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
852        let package =
853            ModelPackage::open(destination).map_err(|reason| AcquisitionError::InvalidPackage {
854                path: destination.to_path_buf(),
855                reason,
856            })?;
857        package
858            .validate_artifact()
859            .map_err(AcquisitionError::Catalog)?;
860        Ok(ModelArtifact {
861            package_path: destination.to_path_buf(),
862            bytes: artifact_size(&package.artifact).map_err(AcquisitionError::Catalog)?,
863            sha256: sha256(&package.artifact).map_err(AcquisitionError::Catalog)?,
864        })
865    }
866}
867
868fn validate_http_uri(uri: &str, allow_insecure_http: bool) -> Result<(), AcquisitionError> {
869    let parsed = reqwest::Url::parse(uri)
870        .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
871    if parsed.scheme() != "https" && !(allow_insecure_http && parsed.scheme() == "http") {
872        return Err(AcquisitionError::InvalidRequest(
873            "model acquisition requires HTTPS".to_owned(),
874        ));
875    }
876    Ok(())
877}
878
879async fn download_body(
880    mut response: reqwest::Response,
881    config: &AcquisitionConfig,
882    cancellation: Option<&CancellationToken>,
883) -> Result<Vec<u8>, AcquisitionError> {
884    let mut body = Vec::new();
885    while let Some(chunk) = response
886        .chunk()
887        .await
888        .map_err(|error| AcquisitionError::Io(error.to_string()))?
889    {
890        if cancellation.is_some_and(CancellationToken::is_cancelled) {
891            return Err(AcquisitionError::Cancelled);
892        }
893        if body.len() as u64 + chunk.len() as u64 > config.max_download_bytes {
894            return Err(AcquisitionError::LimitExceeded {
895                limit: config.max_download_bytes,
896                actual: body.len() as u64 + chunk.len() as u64,
897            });
898        }
899        body.extend_from_slice(&chunk);
900    }
901    Ok(body)
902}
903
904#[derive(Clone)]
905pub struct ModelInstaller {
906    root: PathBuf,
907    catalog: Option<Arc<dyn ModelCatalog>>,
908    config: AcquisitionConfig,
909}
910
911impl ModelInstaller {
912    pub fn new(root: impl Into<PathBuf>) -> Self {
913        Self {
914            root: root.into(),
915            catalog: None,
916            config: AcquisitionConfig::default(),
917        }
918    }
919
920    pub fn with_catalog<C: ModelCatalog + 'static>(mut self, catalog: Arc<C>) -> Self {
921        self.catalog = Some(catalog);
922        self
923    }
924
925    pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
926        self.config = config;
927        self
928    }
929
930    pub async fn install<S: ModelSource>(
931        &self,
932        source: &S,
933        request: &ModelFetchRequest,
934        mode: InstallMode,
935        cancellation: Option<&CancellationToken>,
936    ) -> Result<InstallResult, AcquisitionError> {
937        request
938            .model
939            .validate()
940            .map_err(AcquisitionError::Catalog)?;
941        if let Some(catalog) = &self.catalog {
942            if let Ok(existing) = catalog
943                .resolve(&ModelReference::id(
944                    request.model.name.clone(),
945                    Some(request.model.version.clone()),
946                ))
947                .await
948            {
949                catalog
950                    .validate(&existing.id)
951                    .await
952                    .map_err(AcquisitionError::Catalog)?;
953                if mode == InstallMode::KeepExisting {
954                    return Ok(InstallResult::AlreadyInstalled(existing));
955                }
956            }
957        }
958        if let Some(token) = cancellation {
959            if token.is_cancelled() {
960                return Err(AcquisitionError::Cancelled);
961            }
962        }
963        fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
964        let staging_root = self.root.join(".staging");
965        fs::create_dir_all(&staging_root)
966            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
967        let staging = staging_root.join(format!(
968            "{}-{}-{}",
969            request.model.name,
970            request.model.version,
971            std::process::id()
972        ));
973        if staging.exists() {
974            fs::remove_dir_all(&staging)
975                .map_err(|error| AcquisitionError::Io(error.to_string()))?;
976        }
977        fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
978        let result = async {
979            source
980                .fetch(request, &staging, &self.config, cancellation)
981                .await?;
982            if cancellation.is_some_and(CancellationToken::is_cancelled) {
983                return Err(AcquisitionError::Cancelled);
984            }
985            let package = ModelPackage::open(&staging).map_err(|reason| {
986                AcquisitionError::InvalidPackage {
987                    path: staging.clone(),
988                    reason,
989                }
990            })?;
991            package
992                .validate_artifact()
993                .map_err(AcquisitionError::Catalog)?;
994            let found = package_id(&package)?;
995            if found != request.model {
996                return Err(AcquisitionError::IdentityMismatch {
997                    requested: request.model.clone(),
998                    found,
999                });
1000            }
1001            let final_path = self
1002                .root
1003                .join(&request.model.name)
1004                .join(&request.model.version);
1005            let parent = final_path.parent().expect("model version has a parent");
1006            fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1007            if final_path.exists() {
1008                if mode == InstallMode::Replace {
1009                    let backup = parent.join(format!(".replace-{}", std::process::id()));
1010                    fs::rename(&final_path, &backup)
1011                        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1012                    if let Err(error) = fs::rename(&staging, &final_path) {
1013                        let _ = fs::rename(&backup, &final_path);
1014                        return Err(AcquisitionError::Io(error.to_string()));
1015                    }
1016                    let _ = fs::remove_dir_all(backup);
1017                } else {
1018                    return Err(AcquisitionError::AlreadyInstalled(request.model.clone()));
1019                }
1020            } else {
1021                fs::rename(&staging, &final_path)
1022                    .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1023            }
1024            let catalog = self.catalog.as_ref().ok_or_else(|| {
1025                AcquisitionError::InvalidRequest(
1026                    "a catalog is required to finish installation".to_owned(),
1027                )
1028            })?;
1029            catalog.refresh().await.map_err(AcquisitionError::Catalog)?;
1030            let descriptor = catalog
1031                .resolve(&ModelReference::id(
1032                    request.model.name.clone(),
1033                    Some(request.model.version.clone()),
1034                ))
1035                .await
1036                .map_err(AcquisitionError::Catalog)?;
1037            Ok(InstallResult::Installed(descriptor))
1038        }
1039        .await;
1040        if staging.exists() {
1041            let _ = fs::remove_dir_all(&staging);
1042        }
1043        result
1044    }
1045}
1046
1047fn package_id(package: &ModelPackage) -> Result<ModelId, AcquisitionError> {
1048    let version = package
1049        .manifest
1050        .model_version
1051        .clone()
1052        .or_else(|| package.manifest.version.clone())
1053        .ok_or_else(|| AcquisitionError::InvalidPackage {
1054            path: package.root.clone(),
1055            reason: "model version is required".to_owned(),
1056        })?;
1057    ModelId::new(package.manifest.id.clone(), version).map_err(AcquisitionError::Catalog)
1058}
1059
1060fn copy_package(
1061    source: &Path,
1062    destination: &Path,
1063    limit: u64,
1064    cancellation: Option<&CancellationToken>,
1065) -> Result<(), AcquisitionError> {
1066    let mut bytes = 0;
1067    copy_package_entry(source, destination, &mut bytes, limit, cancellation)?;
1068    Ok(())
1069}
1070
1071fn copy_package_entry(
1072    source: &Path,
1073    destination: &Path,
1074    bytes: &mut u64,
1075    limit: u64,
1076    cancellation: Option<&CancellationToken>,
1077) -> Result<(), AcquisitionError> {
1078    if cancellation.is_some_and(CancellationToken::is_cancelled) {
1079        return Err(AcquisitionError::Cancelled);
1080    }
1081    let metadata =
1082        fs::symlink_metadata(source).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1083    if metadata.file_type().is_symlink() {
1084        return Err(AcquisitionError::InvalidPackage {
1085            path: source.to_path_buf(),
1086            reason: "symbolic links are not allowed".to_owned(),
1087        });
1088    }
1089    if metadata.is_dir() {
1090        fs::create_dir_all(destination).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1091        let mut entries = fs::read_dir(source)
1092            .map_err(|error| AcquisitionError::Io(error.to_string()))?
1093            .collect::<Result<Vec<_>, _>>()
1094            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1095        entries.sort_by_key(|entry| entry.path());
1096        for entry in entries {
1097            copy_package_entry(
1098                &entry.path(),
1099                &destination.join(entry.file_name()),
1100                bytes,
1101                limit,
1102                cancellation,
1103            )?;
1104        }
1105    } else if metadata.is_file() {
1106        *bytes = bytes.saturating_add(metadata.len());
1107        if *bytes > limit {
1108            return Err(AcquisitionError::LimitExceeded {
1109                limit,
1110                actual: *bytes,
1111            });
1112        }
1113        fs::copy(source, destination).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1114    } else {
1115        return Err(AcquisitionError::InvalidPackage {
1116            path: source.to_path_buf(),
1117            reason: "unsupported filesystem entry".to_owned(),
1118        });
1119    }
1120    Ok(())
1121}
1122
1123/// A pinned model package known to the runtime. This is installation metadata,
1124/// not inference behavior; adapters remain responsible for model-specific semantics.
1125#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1126pub struct RegisteredModel {
1127    pub name: String,
1128    pub revision: String,
1129    pub source: String,
1130    pub backend: String,
1131    pub runtime_requirement: String,
1132    pub format: ModelFormat,
1133    #[serde(default)]
1134    pub platforms: Vec<String>,
1135    #[serde(default)]
1136    pub architectures: Vec<String>,
1137    pub artifact_path: String,
1138    pub files: Vec<RegisteredModelFile>,
1139}
1140
1141#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1142pub struct RegisteredModelFile {
1143    pub path: String,
1144    pub sha256: String,
1145}
1146
1147pub const INSTALLATION_MANIFEST_FILE: &str = "installation.json";
1148
1149#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1150#[serde(rename_all = "snake_case")]
1151pub enum CompiledStatus {
1152    Ready,
1153    Missing,
1154    Corrupt,
1155    Unsupported,
1156}
1157
1158#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1159pub struct CompiledArtifactManifest {
1160    pub path: PathBuf,
1161    pub identity: String,
1162}
1163
1164#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1165pub struct InstallationManifest {
1166    pub schema_version: u32,
1167    pub model: String,
1168    pub model_revision: String,
1169    pub model_checksum: String,
1170    pub runtime_version: String,
1171    pub runtime_requirement: String,
1172    pub backend: String,
1173    pub os: String,
1174    pub architecture: String,
1175    pub installed_at_unix_seconds: u64,
1176    pub compiled_status: CompiledStatus,
1177    pub compiled_artifact: Option<CompiledArtifactManifest>,
1178}
1179
1180impl InstallationManifest {
1181    pub fn read(package: &Path) -> Result<Self, AcquisitionError> {
1182        let path = package.join(INSTALLATION_MANIFEST_FILE);
1183        let bytes = fs::read(&path).map_err(|error| AcquisitionError::InvalidPackage {
1184            path: path.clone(),
1185            reason: format!(
1186                "installation is not ready: {error}; run `ml-runtime model doctor {}`",
1187                package
1188                    .parent()
1189                    .and_then(Path::file_name)
1190                    .and_then(|name| name.to_str())
1191                    .unwrap_or("MODEL")
1192            ),
1193        })?;
1194        serde_json::from_slice(&bytes).map_err(|error| AcquisitionError::InvalidPackage {
1195            path,
1196            reason: format!("invalid installation manifest: {error}"),
1197        })
1198    }
1199
1200    pub fn write_atomic(&self, package: &Path) -> Result<(), AcquisitionError> {
1201        let destination = package.join(INSTALLATION_MANIFEST_FILE);
1202        let temporary = package.join(format!(".{INSTALLATION_MANIFEST_FILE}.tmp"));
1203        let bytes = serde_json::to_vec_pretty(self)
1204            .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
1205        let mut output = fs::File::create(&temporary)
1206            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1207        output
1208            .write_all(&bytes)
1209            .and_then(|()| output.sync_all())
1210            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1211        fs::rename(&temporary, &destination)
1212            .map_err(|error| AcquisitionError::Io(error.to_string()))
1213    }
1214}
1215
1216#[derive(Clone, Debug, Default)]
1217pub struct BuiltinModelRegistry;
1218
1219impl BuiltinModelRegistry {
1220    pub fn list(&self) -> Vec<RegisteredModel> {
1221        self.all()
1222            .into_iter()
1223            .filter(|model| model.supports_platform(std::env::consts::OS, std::env::consts::ARCH))
1224            .collect()
1225    }
1226
1227    pub fn resolve(&self, name: &str) -> Result<RegisteredModel, AcquisitionError> {
1228        self.resolve_for(name, std::env::consts::OS, std::env::consts::ARCH)
1229    }
1230
1231    pub fn resolve_for(
1232        &self,
1233        name: &str,
1234        platform: &str,
1235        architecture: &str,
1236    ) -> Result<RegisteredModel, AcquisitionError> {
1237        let registrations: Vec<_> = self
1238            .all()
1239            .into_iter()
1240            .filter(|model| model.name == name)
1241            .collect();
1242        if registrations.is_empty() {
1243            return Err(AcquisitionError::InvalidRequest(format!(
1244                "unknown registered model {name:?}"
1245            )));
1246        }
1247        registrations
1248            .iter()
1249            .find(|model| model.supports_platform(platform, architecture))
1250            .cloned()
1251            .ok_or_else(|| AcquisitionError::InvalidRequest(format!(
1252                "registered model {name:?} has no backend for platform {platform}/{architecture}; available variants: {}",
1253                registrations
1254                    .iter()
1255                    .map(|model| format!("{} ({}/{})", model.backend, model.platforms.join("|"), model.architectures.join("|")))
1256                    .collect::<Vec<_>>()
1257                    .join(", ")
1258            )))
1259    }
1260
1261    fn all(&self) -> Vec<RegisteredModel> {
1262        vec![laya_coreml_registration(), laya_onnx_registration()]
1263    }
1264}
1265
1266impl RegisteredModel {
1267    pub fn supports_platform(&self, platform: &str, architecture: &str) -> bool {
1268        (self.platforms.is_empty() || self.platforms.iter().any(|value| value == platform))
1269            && (self.architectures.is_empty()
1270                || self.architectures.iter().any(|value| value == architecture))
1271    }
1272}
1273
1274fn laya_coreml_registration() -> RegisteredModel {
1275    const REVISION: &str = "fff78b2d9750c6b748fe8c90fcbf8bed0a1522a9";
1276    let files = [
1277        (
1278            "coreml_config.json",
1279            "990b99a736f64c87da57b203d7953c4c1c79c18b615580db894e9c24bda42ab5",
1280        ),
1281        (
1282            "validation.json",
1283            "709e1a0ac95a7bf73df0b5a8582423c9f40c80a1b4edd3499a77a1ac2ac39731",
1284        ),
1285        (
1286            "encoder/config.json",
1287            "bf3ab80598fdccf414855a2ce80f22859e4492d06ca8a62ddd1cfb63972f8979",
1288        ),
1289        (
1290            "rl_agent_config.json",
1291            "ae287b56bbcf5f8c4f4541ae9dfd00c914c4c48b940b8398c3058af37ba92bbd",
1292        ),
1293        (
1294            "tokenizer/tokenizer.json",
1295            "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1296        ),
1297        (
1298            "tokenizer/tokenizer_config.json",
1299            "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1300        ),
1301        (
1302            "model.mlpackage/Manifest.json",
1303            "41bab6e532f727e8809c76906f41026a48ef9b276c56068b3d68270a13981e20",
1304        ),
1305        (
1306            "model.mlpackage/Data/com.apple.CoreML/model.mlmodel",
1307            "dc6a6383ad4a2f04f7525924b0dfb830429dedc44387f143a2f87782e39aeab0",
1308        ),
1309        (
1310            "model.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
1311            "5872b9f6530c20a845b69c0cb75aa141e9c89ffdd5f36529c3708cec9b7a7a83",
1312        ),
1313    ]
1314    .into_iter()
1315    .map(|(path, sha256)| RegisteredModelFile {
1316        path: path.to_owned(),
1317        sha256: sha256.to_owned(),
1318    })
1319    .collect();
1320    RegisteredModel {
1321        name: "laya".to_owned(),
1322        revision: REVISION.to_owned(),
1323        source: format!("https://huggingface.co/aac6fef/laya-coreml/resolve/{REVISION}"),
1324        backend: "coreml".to_owned(),
1325        runtime_requirement: ">=0.1.0".to_owned(),
1326        format: ModelFormat::CoreMl,
1327        platforms: vec!["macos".to_owned()],
1328        architectures: vec!["aarch64".to_owned()],
1329        artifact_path: "model.mlpackage".to_owned(),
1330        files,
1331    }
1332}
1333
1334fn laya_onnx_registration() -> RegisteredModel {
1335    const REVISION: &str = "68f27dfe5a27a54fb2b1fefc432f43f972e90868";
1336    let files = [
1337        (
1338            "laya.onnx",
1339            "a874eb254b58b0fcb1e7ad56fbb188c29d64e08c9a46b689433e1f52c66dba1e",
1340        ),
1341        (
1342            "laya.onnx.data",
1343            "487746363a8da57bcadb4345352997d22a0fb90d70aa22c6856668d023242aba",
1344        ),
1345        (
1346            "laya_config.json",
1347            "5049005dc6ae3ca5e82cc7d85c421357d5c543817300c8e8c5281ddbc69bb561",
1348        ),
1349        (
1350            "tokenizer/tokenizer.json",
1351            "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1352        ),
1353        (
1354            "tokenizer/tokenizer_config.json",
1355            "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1356        ),
1357    ]
1358    .into_iter()
1359    .map(|(path, sha256)| RegisteredModelFile {
1360        path: path.to_owned(),
1361        sha256: sha256.to_owned(),
1362    })
1363    .collect();
1364    RegisteredModel {
1365        name: "laya".to_owned(),
1366        revision: REVISION.to_owned(),
1367        source: format!("https://huggingface.co/receptron/laya-onnx/resolve/{REVISION}"),
1368        backend: "onnx".to_owned(),
1369        runtime_requirement: ">=0.2.2".to_owned(),
1370        format: ModelFormat::Onnx,
1371        platforms: vec!["linux".to_owned()],
1372        architectures: vec!["x86_64".to_owned(), "aarch64".to_owned()],
1373        artifact_path: "laya.onnx".to_owned(),
1374        files,
1375    }
1376}
1377
1378pub fn default_model_root() -> Result<PathBuf, AcquisitionError> {
1379    if let Some(root) = std::env::var_os("ML_RUNTIME_MODEL_DIR") {
1380        return Ok(PathBuf::from(root));
1381    }
1382    #[cfg(target_os = "windows")]
1383    if let Some(root) = std::env::var_os("LOCALAPPDATA") {
1384        return Ok(PathBuf::from(root).join("ml-runtime/models"));
1385    }
1386    let home = std::env::var_os("HOME").ok_or_else(|| {
1387        AcquisitionError::InvalidRequest(
1388            "cannot determine model directory; set ML_RUNTIME_MODEL_DIR".to_owned(),
1389        )
1390    })?;
1391    #[cfg(target_os = "windows")]
1392    return Ok(PathBuf::from(home).join("AppData/Local/ml-runtime/models"));
1393    #[cfg(target_os = "macos")]
1394    return Ok(PathBuf::from(home).join("Library/Application Support/ml-runtime/models"));
1395    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
1396    Ok(PathBuf::from(home).join(".local/share/ml-runtime/models"))
1397}
1398
1399#[derive(Clone, Debug, PartialEq, Eq)]
1400pub struct RegisteredInstallResult {
1401    pub package_path: PathBuf,
1402    pub already_installed: bool,
1403}
1404
1405pub struct RegisteredModelInstaller {
1406    root: PathBuf,
1407    client: reqwest::Client,
1408    config: AcquisitionConfig,
1409}
1410
1411impl RegisteredModelInstaller {
1412    pub fn new(root: impl Into<PathBuf>) -> Result<Self, AcquisitionError> {
1413        let client = reqwest::Client::builder()
1414            .redirect(reqwest::redirect::Policy::limited(10))
1415            .build()
1416            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1417        Ok(Self {
1418            root: root.into(),
1419            client,
1420            config: AcquisitionConfig::default(),
1421        })
1422    }
1423
1424    pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
1425        self.config = config;
1426        self
1427    }
1428
1429    pub fn installed_path(&self, model: &RegisteredModel) -> PathBuf {
1430        self.root.join(&model.name).join(&model.revision)
1431    }
1432
1433    pub fn validate(
1434        &self,
1435        model: &RegisteredModel,
1436        package: &Path,
1437    ) -> Result<(), AcquisitionError> {
1438        validate_registration(model)?;
1439        let manifest =
1440            ModelPackage::open(package).map_err(|reason| AcquisitionError::InvalidPackage {
1441                path: package.to_path_buf(),
1442                reason,
1443            })?;
1444        let id = package_id(&manifest)?;
1445        let expected =
1446            ModelId::new(&model.name, &model.revision).map_err(AcquisitionError::Catalog)?;
1447        if id != expected || manifest.manifest.format != model.format {
1448            return Err(AcquisitionError::IdentityMismatch {
1449                requested: expected,
1450                found: id,
1451            });
1452        }
1453        if manifest.manifest.artifact.path != model.artifact_path {
1454            return Err(AcquisitionError::InvalidPackage {
1455                path: package.to_path_buf(),
1456                reason: format!(
1457                    "registered artifact path must be {:?}, got {:?}",
1458                    model.artifact_path, manifest.manifest.artifact.path
1459                ),
1460            });
1461        }
1462        for (key, expected) in [
1463            ("backend", model.backend.as_str()),
1464            ("platforms", model.platforms.join(",").as_str()),
1465            ("architectures", model.architectures.join(",").as_str()),
1466        ] {
1467            if manifest.manifest.metadata.get(key).map(String::as_str) != Some(expected) {
1468                return Err(AcquisitionError::InvalidPackage {
1469                    path: package.join("manifest.json"),
1470                    reason: format!("registered metadata {key:?} is missing or incorrect"),
1471                });
1472            }
1473        }
1474        if !runtime_requirement_satisfied(&model.runtime_requirement, env!("CARGO_PKG_VERSION")) {
1475            return Err(AcquisitionError::InvalidPackage {
1476                path: package.to_path_buf(),
1477                reason: format!(
1478                    "model requires runtime {}, current runtime is {}",
1479                    model.runtime_requirement,
1480                    env!("CARGO_PKG_VERSION")
1481                ),
1482            });
1483        }
1484        for file in &model.files {
1485            let path = safe_registered_path(package, &file.path)?;
1486            let actual = sha256_file_streaming(&path)?;
1487            if !actual.eq_ignore_ascii_case(&file.sha256) {
1488                return Err(AcquisitionError::InvalidPackage {
1489                    path,
1490                    reason: format!("sha256 mismatch: expected {}, got {actual}", file.sha256),
1491                });
1492            }
1493        }
1494        Ok(())
1495    }
1496
1497    pub async fn install(
1498        &self,
1499        model: &RegisteredModel,
1500        source_override: Option<&str>,
1501        mode: InstallMode,
1502        cancellation: Option<&CancellationToken>,
1503    ) -> Result<RegisteredInstallResult, AcquisitionError> {
1504        validate_registration(model)?;
1505        if !model.supports_platform(std::env::consts::OS, std::env::consts::ARCH) {
1506            return Err(AcquisitionError::InvalidRequest(format!(
1507                "model {} backend {} does not support {}/{}",
1508                model.name,
1509                model.backend,
1510                std::env::consts::OS,
1511                std::env::consts::ARCH
1512            )));
1513        }
1514        let final_path = self.installed_path(model);
1515        if final_path.exists() && mode == InstallMode::KeepExisting {
1516            self.validate(model, &final_path)?;
1517            return Ok(RegisteredInstallResult {
1518                package_path: final_path,
1519                already_installed: true,
1520            });
1521        }
1522        fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1523        let staging_root = self.root.join(".staging");
1524        fs::create_dir_all(&staging_root)
1525            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1526        let staging = staging_root.join(format!("{}-{}", model.name, std::process::id()));
1527        if staging.exists() {
1528            fs::remove_dir_all(&staging)
1529                .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1530        }
1531        fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1532        let source = source_override.unwrap_or(&model.source);
1533        let result = async {
1534            let mut downloaded = 0_u64;
1535            if source.starts_with("https://") || source.starts_with("http://") {
1536                validate_http_uri(source, false)?;
1537                for file in &model.files {
1538                    if cancellation.is_some_and(CancellationToken::is_cancelled) {
1539                        return Err(AcquisitionError::Cancelled);
1540                    }
1541                    let destination = safe_registered_path(&staging, &file.path)?;
1542                    if let Some(parent) = destination.parent() {
1543                        fs::create_dir_all(parent)
1544                            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1545                    }
1546                    self.download_file(
1547                        &format!("{}/{}", source.trim_end_matches('/'), file.path),
1548                        &destination,
1549                        &mut downloaded,
1550                        cancellation,
1551                    )
1552                    .await?;
1553                }
1554            } else {
1555                let source = Path::new(source);
1556                if !source.is_dir() {
1557                    return Err(AcquisitionError::InvalidRequest(format!(
1558                        "registered model source is not a directory: {}",
1559                        source.display()
1560                    )));
1561                }
1562                for file in &model.files {
1563                    let from = safe_registered_path(source, &file.path)?;
1564                    let to = safe_registered_path(&staging, &file.path)?;
1565                    if let Some(parent) = to.parent() {
1566                        fs::create_dir_all(parent)
1567                            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1568                    }
1569                    let size = fs::metadata(&from)
1570                        .map_err(|error| AcquisitionError::Io(error.to_string()))?
1571                        .len();
1572                    downloaded = downloaded.saturating_add(size);
1573                    if downloaded > self.config.max_download_bytes {
1574                        return Err(AcquisitionError::LimitExceeded {
1575                            limit: self.config.max_download_bytes,
1576                            actual: downloaded,
1577                        });
1578                    }
1579                    fs::copy(&from, &to)
1580                        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1581                }
1582            }
1583            write_registered_manifest(&staging, model)?;
1584            self.validate(model, &staging)?;
1585            let parent = final_path.parent().expect("registered model has parent");
1586            fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1587            if final_path.exists() {
1588                if mode != InstallMode::Replace {
1589                    return Err(AcquisitionError::AlreadyInstalled(
1590                        ModelId::new(&model.name, &model.revision)
1591                            .map_err(AcquisitionError::Catalog)?,
1592                    ));
1593                }
1594                let backup = parent.join(format!(".replace-{}", std::process::id()));
1595                fs::rename(&final_path, &backup)
1596                    .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1597                if let Err(error) = fs::rename(&staging, &final_path) {
1598                    let _ = fs::rename(&backup, &final_path);
1599                    return Err(AcquisitionError::Io(error.to_string()));
1600                }
1601                let _ = fs::remove_dir_all(backup);
1602            } else {
1603                fs::rename(&staging, &final_path)
1604                    .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1605            }
1606            Ok(RegisteredInstallResult {
1607                package_path: final_path.clone(),
1608                already_installed: false,
1609            })
1610        }
1611        .await;
1612        if staging.exists() {
1613            let _ = fs::remove_dir_all(staging);
1614        }
1615        result
1616    }
1617
1618    async fn download_file(
1619        &self,
1620        url: &str,
1621        destination: &Path,
1622        downloaded: &mut u64,
1623        cancellation: Option<&CancellationToken>,
1624    ) -> Result<(), AcquisitionError> {
1625        validate_http_uri(url, false)?;
1626        let mut response = tokio::time::timeout(
1627            std::time::Duration::from_secs(self.config.timeout_secs),
1628            self.client.get(url).send(),
1629        )
1630        .await
1631        .map_err(|_| AcquisitionError::Io(format!("download timed out: {url}")))?
1632        .map_err(|error| AcquisitionError::Io(error.to_string()))?
1633        .error_for_status()
1634        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1635        let mut output = fs::File::create(destination)
1636            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1637        while let Some(chunk) = response
1638            .chunk()
1639            .await
1640            .map_err(|error| AcquisitionError::Io(error.to_string()))?
1641        {
1642            if cancellation.is_some_and(CancellationToken::is_cancelled) {
1643                return Err(AcquisitionError::Cancelled);
1644            }
1645            *downloaded = downloaded.saturating_add(chunk.len() as u64);
1646            if *downloaded > self.config.max_download_bytes {
1647                return Err(AcquisitionError::LimitExceeded {
1648                    limit: self.config.max_download_bytes,
1649                    actual: *downloaded,
1650                });
1651            }
1652            output
1653                .write_all(&chunk)
1654                .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1655        }
1656        output
1657            .sync_all()
1658            .map_err(|error| AcquisitionError::Io(error.to_string()))
1659    }
1660}
1661
1662fn validate_registration(model: &RegisteredModel) -> Result<(), AcquisitionError> {
1663    if model.name.is_empty()
1664        || model.revision.is_empty()
1665        || model.source.is_empty()
1666        || model.backend.is_empty()
1667        || model.artifact_path.is_empty()
1668        || model.platforms.iter().any(String::is_empty)
1669        || model.architectures.iter().any(String::is_empty)
1670    {
1671        return Err(AcquisitionError::InvalidRequest(
1672            "registered model metadata is incomplete".to_owned(),
1673        ));
1674    }
1675    let mut paths = std::collections::BTreeSet::new();
1676    for file in &model.files {
1677        if !paths.insert(&file.path)
1678            || file.sha256.len() != 64
1679            || !file.sha256.bytes().all(|byte| byte.is_ascii_hexdigit())
1680        {
1681            return Err(AcquisitionError::InvalidRequest(format!(
1682                "registered file {:?} has a duplicate path or invalid SHA-256",
1683                file.path
1684            )));
1685        }
1686    }
1687    if !paths.contains(&model.artifact_path)
1688        && !paths
1689            .iter()
1690            .any(|path| path.starts_with(&format!("{}/", model.artifact_path)))
1691    {
1692        return Err(AcquisitionError::InvalidRequest(format!(
1693            "registered artifact {:?} has no checksummed file entry",
1694            model.artifact_path
1695        )));
1696    }
1697    Ok(())
1698}
1699
1700fn safe_registered_path(root: &Path, relative: &str) -> Result<PathBuf, AcquisitionError> {
1701    let relative = Path::new(relative);
1702    if relative.is_absolute()
1703        || relative
1704            .components()
1705            .any(|component| !matches!(component, std::path::Component::Normal(_)))
1706    {
1707        return Err(AcquisitionError::InvalidRequest(
1708            "registered file path must remain inside the package".to_owned(),
1709        ));
1710    }
1711    Ok(root.join(relative))
1712}
1713
1714fn sha256_file_streaming(path: &Path) -> Result<String, AcquisitionError> {
1715    let mut file = fs::File::open(path).map_err(|error| AcquisitionError::InvalidPackage {
1716        path: path.to_path_buf(),
1717        reason: error.to_string(),
1718    })?;
1719    let mut digest = Sha256::new();
1720    let mut buffer = vec![0_u8; 8 * 1024 * 1024];
1721    loop {
1722        let count = file
1723            .read(&mut buffer)
1724            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1725        if count == 0 {
1726            break;
1727        }
1728        digest.update(&buffer[..count]);
1729    }
1730    Ok(format!("{:x}", digest.finalize()))
1731}
1732
1733fn write_registered_manifest(
1734    destination: &Path,
1735    model: &RegisteredModel,
1736) -> Result<(), AcquisitionError> {
1737    let manifest = ModelManifest {
1738        schema_version: 1,
1739        id: model.name.clone(),
1740        model_version: Some(model.revision.clone()),
1741        version: None,
1742        format: model.format.clone(),
1743        artifact: ArtifactSpec {
1744            path: model.artifact_path.clone(),
1745            size_bytes: None,
1746            sha256: None,
1747        },
1748        metadata: BTreeMap::from([
1749            ("backend".to_owned(), model.backend.clone()),
1750            ("platforms".to_owned(), model.platforms.join(",")),
1751            ("architectures".to_owned(), model.architectures.join(",")),
1752            ("source".to_owned(), model.source.clone()),
1753            ("registry_revision".to_owned(), model.revision.clone()),
1754            (
1755                "runtime_requirement".to_owned(),
1756                model.runtime_requirement.clone(),
1757            ),
1758        ]),
1759        inputs: Vec::new(),
1760        outputs: Vec::new(),
1761    };
1762    fs::write(
1763        destination.join("manifest.json"),
1764        serde_json::to_vec_pretty(&manifest)
1765            .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?,
1766    )
1767    .map_err(|error| AcquisitionError::Io(error.to_string()))
1768}
1769
1770pub fn runtime_requirement_satisfied(requirement: &str, current: &str) -> bool {
1771    let Some(required) = requirement.strip_prefix(">=") else {
1772        return requirement == current || requirement == "*";
1773    };
1774    let key = |version: &str| {
1775        let mut parts = version
1776            .split('.')
1777            .map(|part| part.parse::<u64>().unwrap_or(0));
1778        (
1779            parts.next().unwrap_or(0),
1780            parts.next().unwrap_or(0),
1781            parts.next().unwrap_or(0),
1782        )
1783    };
1784    key(current) >= key(required)
1785}
1786
1787#[derive(Clone)]
1788pub struct ModelHandle {
1789    model_id: String,
1790    backend: String,
1791    format: ModelFormat,
1792    inner: Arc<dyn Any + Send + Sync>,
1793}
1794
1795impl ModelHandle {
1796    pub fn new(
1797        model_id: impl Into<String>,
1798        backend: impl Into<String>,
1799        format: ModelFormat,
1800        inner: Arc<dyn Any + Send + Sync>,
1801    ) -> Self {
1802        Self {
1803            model_id: model_id.into(),
1804            backend: backend.into(),
1805            format,
1806            inner,
1807        }
1808    }
1809
1810    pub fn id(&self) -> &str {
1811        &self.model_id
1812    }
1813
1814    pub fn backend(&self) -> &str {
1815        &self.backend
1816    }
1817
1818    pub fn format(&self) -> &ModelFormat {
1819        &self.format
1820    }
1821
1822    pub fn state<T: Any + Send + Sync>(&self) -> Option<&T> {
1823        self.inner.as_ref().downcast_ref::<T>()
1824    }
1825}
1826
1827impl std::fmt::Debug for ModelHandle {
1828    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1829        f.debug_struct("ModelHandle")
1830            .field("model_id", &self.model_id)
1831            .field("backend", &self.backend)
1832            .field("format", &self.format)
1833            .finish_non_exhaustive()
1834    }
1835}
1836
1837#[cfg(test)]
1838mod tests {
1839    use super::{
1840        ArtifactSpec, BuiltinModelRegistry, CompiledArtifactManifest, CompiledStatus,
1841        FilesystemModelCatalog, InstallMode, InstallationManifest, ModelCatalog, ModelFormat,
1842        ModelManifest, ModelReference, RegisteredModel, RegisteredModelFile,
1843        RegisteredModelInstaller,
1844    };
1845    use std::{fs, path::PathBuf};
1846
1847    #[test]
1848    fn accepts_lowercase_manifest_formats() {
1849        let manifest: ModelManifest = serde_json::from_str(
1850            r#"{"id":"example","format":"onnx","artifact":"artifacts/model.onnx"}"#,
1851        )
1852        .unwrap();
1853        assert_eq!(manifest.format, ModelFormat::Onnx);
1854    }
1855
1856    #[test]
1857    fn builtin_registry_pins_laya_distribution_metadata() {
1858        let coreml = BuiltinModelRegistry
1859            .resolve_for("laya", "macos", "aarch64")
1860            .unwrap();
1861        assert_eq!(coreml.backend, "coreml");
1862        assert_eq!(coreml.format, ModelFormat::CoreMl);
1863        assert_eq!(coreml.artifact_path, "model.mlpackage");
1864        assert!(coreml.source.contains(&coreml.revision));
1865        assert!(coreml
1866            .files
1867            .iter()
1868            .any(|file| file.path.ends_with("weights/weight.bin")));
1869        let onnx = BuiltinModelRegistry
1870            .resolve_for("laya", "linux", "x86_64")
1871            .unwrap();
1872        assert_eq!(onnx.backend, "onnx");
1873        assert_eq!(onnx.format, ModelFormat::Onnx);
1874        assert_eq!(onnx.artifact_path, "laya.onnx");
1875        assert!(onnx.files.iter().all(|file| file.sha256.len() == 64));
1876        assert!(BuiltinModelRegistry
1877            .resolve_for("laya", "windows", "x86_64")
1878            .unwrap_err()
1879            .to_string()
1880            .contains("no backend for platform"));
1881        assert!(BuiltinModelRegistry.resolve("missing").is_err());
1882    }
1883
1884    #[test]
1885    fn installation_manifest_round_trips_atomically() {
1886        let root = std::env::temp_dir().join(format!(
1887            "ml-runtime-installation-manifest-{}",
1888            std::process::id()
1889        ));
1890        fs::create_dir_all(&root).unwrap();
1891        let manifest = InstallationManifest {
1892            schema_version: 1,
1893            model: "laya".to_owned(),
1894            model_revision: "revision".to_owned(),
1895            model_checksum: "model-hash".to_owned(),
1896            runtime_version: "0.1.0".to_owned(),
1897            runtime_requirement: ">=0.1.0".to_owned(),
1898            backend: "coreml".to_owned(),
1899            os: "macos".to_owned(),
1900            architecture: "aarch64".to_owned(),
1901            installed_at_unix_seconds: 1,
1902            compiled_status: CompiledStatus::Ready,
1903            compiled_artifact: Some(CompiledArtifactManifest {
1904                path: root.join("compiled.mlmodelc"),
1905                identity: "compiled-hash".to_owned(),
1906            }),
1907        };
1908        manifest.write_atomic(&root).unwrap();
1909        assert_eq!(InstallationManifest::read(&root).unwrap(), manifest);
1910        assert!(!root.join(".installation.json.tmp").exists());
1911        let _ = fs::remove_dir_all(root);
1912    }
1913
1914    #[tokio::test]
1915    async fn registered_installer_discovers_validates_and_rejects_corruption() {
1916        let root = std::env::temp_dir().join(format!(
1917            "ml-runtime-registered-install-{}",
1918            std::process::id()
1919        ));
1920        let source = root.join("source");
1921        let installed = root.join("installed");
1922        std::fs::create_dir_all(source.join("model.mlpackage")).unwrap();
1923        std::fs::write(source.join("config.json"), b"config").unwrap();
1924        std::fs::write(source.join("model.mlpackage/Manifest.json"), b"package").unwrap();
1925        let digest = |path: &std::path::Path| super::sha256_file_streaming(path).unwrap();
1926        let model = RegisteredModel {
1927            name: "fixture".to_owned(),
1928            revision: "revision-1".to_owned(),
1929            source: "https://example.invalid/fixture".to_owned(),
1930            backend: "coreml".to_owned(),
1931            runtime_requirement: ">=0.1.0".to_owned(),
1932            format: ModelFormat::CoreMl,
1933            platforms: vec![],
1934            architectures: vec![],
1935            artifact_path: "model.mlpackage".to_owned(),
1936            files: vec![
1937                RegisteredModelFile {
1938                    path: "config.json".to_owned(),
1939                    sha256: digest(&source.join("config.json")),
1940                },
1941                RegisteredModelFile {
1942                    path: "model.mlpackage/Manifest.json".to_owned(),
1943                    sha256: digest(&source.join("model.mlpackage/Manifest.json")),
1944                },
1945            ],
1946        };
1947        let installer = RegisteredModelInstaller::new(&installed).unwrap();
1948        let result = installer
1949            .install(
1950                &model,
1951                Some(source.to_str().unwrap()),
1952                InstallMode::KeepExisting,
1953                None,
1954            )
1955            .await
1956            .unwrap();
1957        assert_eq!(result.package_path, installed.join("fixture/revision-1"));
1958        assert!(result.package_path.join("manifest.json").is_file());
1959        installer.validate(&model, &result.package_path).unwrap();
1960
1961        let existing = installer
1962            .install(
1963                &model,
1964                Some(source.to_str().unwrap()),
1965                InstallMode::KeepExisting,
1966                None,
1967            )
1968            .await
1969            .unwrap();
1970        assert!(existing.already_installed);
1971        std::fs::write(existing.package_path.join("config.json"), b"corrupt").unwrap();
1972        assert!(installer.validate(&model, &existing.package_path).is_err());
1973        let _ = std::fs::remove_dir_all(root);
1974    }
1975
1976    #[test]
1977    fn registered_model_rejects_missing_or_malformed_checksums() {
1978        let root = std::env::temp_dir().join(format!(
1979            "ml-runtime-registration-validation-{}",
1980            std::process::id()
1981        ));
1982        let installer = RegisteredModelInstaller::new(&root).unwrap();
1983        let mut model = RegisteredModel {
1984            name: "fixture".to_owned(),
1985            revision: "revision".to_owned(),
1986            source: "https://example.invalid/model".to_owned(),
1987            backend: "onnx".to_owned(),
1988            runtime_requirement: ">=0.1.0".to_owned(),
1989            format: ModelFormat::Onnx,
1990            platforms: vec![],
1991            architectures: vec![],
1992            artifact_path: "model.onnx".to_owned(),
1993            files: vec![],
1994        };
1995        assert!(super::validate_registration(&model).is_err());
1996        model.files.push(RegisteredModelFile {
1997            path: "model.onnx".to_owned(),
1998            sha256: "not-a-sha256".to_owned(),
1999        });
2000        assert!(super::validate_registration(&model).is_err());
2001        assert!(installer.validate(&model, &root).is_err());
2002    }
2003
2004    #[test]
2005    fn accepts_artifact_integrity_metadata() {
2006        let manifest: ModelManifest = serde_json::from_str(
2007            r#"{"id":"example","format":"onnx","artifact":{"path":"model.onnx","size_bytes":3,"sha256":"abc"}}"#,
2008        )
2009        .unwrap();
2010        assert_eq!(
2011            manifest.artifact,
2012            ArtifactSpec {
2013                path: "model.onnx".to_owned(),
2014                size_bytes: Some(3),
2015                sha256: Some("abc".to_owned()),
2016            }
2017        );
2018    }
2019
2020    #[tokio::test]
2021    async fn discovers_and_resolves_existing_packages_deterministically() {
2022        let root = std::env::temp_dir().join(format!("ml-runtime-catalog-{}", std::process::id()));
2023        let first = root.join("nested/example-linear");
2024        fs::create_dir_all(first.join("artifacts")).unwrap();
2025        fs::write(
2026            first.join("manifest.json"),
2027            r#"{"id":"example-linear","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.json"}"#,
2028        )
2029        .unwrap();
2030        fs::write(first.join("artifacts/model.json"), "{}").unwrap();
2031
2032        let catalog = FilesystemModelCatalog::new(&root);
2033        let models = catalog.list().await.unwrap();
2034        assert_eq!(models[0].id.to_string(), "example-linear@1.0.0");
2035        let resolved = catalog
2036            .resolve(&ModelReference::id(
2037                "example-linear",
2038                Some("1.0.0".to_owned()),
2039            ))
2040            .await
2041            .unwrap();
2042        assert_eq!(resolved.package_path, PathBuf::from(&first));
2043        fs::remove_dir_all(root).unwrap();
2044    }
2045
2046    #[tokio::test]
2047    async fn installs_verified_package_atomically_and_refreshes_catalog() {
2048        use super::{
2049            AcquisitionConfig, FileModelSource, InstallMode, InstallResult, ModelFetchRequest,
2050            ModelId, ModelInstaller, ModelSourceReference,
2051        };
2052        use std::sync::Arc;
2053        let root = std::env::temp_dir().join(format!("ml-runtime-install-{}", std::process::id()));
2054        let source_root = root.join("source");
2055        let catalog_root = root.join("models");
2056        fs::create_dir_all(source_root.join("artifacts")).unwrap();
2057        fs::write(
2058            source_root.join("manifest.json"),
2059            r#"{"id":"acquired","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
2060        )
2061        .unwrap();
2062        fs::write(source_root.join("artifacts/model.bin"), b"model").unwrap();
2063
2064        let catalog = Arc::new(FilesystemModelCatalog::new(&catalog_root));
2065        let installer = ModelInstaller::new(&catalog_root)
2066            .with_catalog(Arc::clone(&catalog))
2067            .with_config(AcquisitionConfig {
2068                max_download_bytes: 1024,
2069                timeout_secs: 30,
2070            });
2071        let request = ModelFetchRequest {
2072            model: ModelId::new("acquired", "1.0.0").unwrap(),
2073            source: ModelSourceReference::Path(source_root.clone()),
2074        };
2075        let result = installer
2076            .install(
2077                &FileModelSource::new(),
2078                &request,
2079                InstallMode::KeepExisting,
2080                None,
2081            )
2082            .await
2083            .unwrap();
2084        assert!(matches!(result, InstallResult::Installed(_)));
2085        assert_eq!(catalog.list().await.unwrap().len(), 1);
2086        let existing = installer
2087            .install(
2088                &FileModelSource::new(),
2089                &request,
2090                InstallMode::KeepExisting,
2091                None,
2092            )
2093            .await
2094            .unwrap();
2095        assert!(matches!(existing, InstallResult::AlreadyInstalled(_)));
2096        assert!(!catalog_root
2097            .join(".staging")
2098            .join("acquired-1.0.0-")
2099            .exists());
2100        fs::remove_dir_all(root).unwrap();
2101    }
2102
2103    #[tokio::test]
2104    async fn rejects_identity_mismatch_without_catalog_entry() {
2105        use super::{
2106            FileModelSource, InstallMode, ModelFetchRequest, ModelId, ModelInstaller,
2107            ModelSourceReference,
2108        };
2109        use std::sync::Arc;
2110        let root = std::env::temp_dir().join(format!("ml-runtime-mismatch-{}", std::process::id()));
2111        let source = root.join("source");
2112        fs::create_dir_all(source.join("artifacts")).unwrap();
2113        fs::write(
2114            source.join("manifest.json"),
2115            r#"{"id":"other","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
2116        )
2117        .unwrap();
2118        fs::write(source.join("artifacts/model.bin"), b"model").unwrap();
2119        let catalog = Arc::new(FilesystemModelCatalog::new(root.join("models")));
2120        let installer = ModelInstaller::new(root.join("models")).with_catalog(Arc::clone(&catalog));
2121        let request = ModelFetchRequest {
2122            model: ModelId::new("requested", "1.0.0").unwrap(),
2123            source: ModelSourceReference::Path(source),
2124        };
2125        assert!(matches!(
2126            installer
2127                .install(
2128                    &FileModelSource::new(),
2129                    &request,
2130                    InstallMode::KeepExisting,
2131                    None
2132                )
2133                .await,
2134            Err(super::AcquisitionError::IdentityMismatch { .. })
2135        ));
2136        assert!(catalog.list().await.unwrap().is_empty());
2137        fs::remove_dir_all(root).unwrap();
2138    }
2139}