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    pub artifact_path: String,
1134    pub files: Vec<RegisteredModelFile>,
1135}
1136
1137#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1138pub struct RegisteredModelFile {
1139    pub path: String,
1140    pub sha256: String,
1141}
1142
1143pub const INSTALLATION_MANIFEST_FILE: &str = "installation.json";
1144
1145#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1146#[serde(rename_all = "snake_case")]
1147pub enum CompiledStatus {
1148    Ready,
1149    Missing,
1150    Corrupt,
1151    Unsupported,
1152}
1153
1154#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1155pub struct CompiledArtifactManifest {
1156    pub path: PathBuf,
1157    pub identity: String,
1158}
1159
1160#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1161pub struct InstallationManifest {
1162    pub schema_version: u32,
1163    pub model: String,
1164    pub model_revision: String,
1165    pub model_checksum: String,
1166    pub runtime_version: String,
1167    pub runtime_requirement: String,
1168    pub backend: String,
1169    pub os: String,
1170    pub architecture: String,
1171    pub installed_at_unix_seconds: u64,
1172    pub compiled_status: CompiledStatus,
1173    pub compiled_artifact: Option<CompiledArtifactManifest>,
1174}
1175
1176impl InstallationManifest {
1177    pub fn read(package: &Path) -> Result<Self, AcquisitionError> {
1178        let path = package.join(INSTALLATION_MANIFEST_FILE);
1179        let bytes = fs::read(&path).map_err(|error| AcquisitionError::InvalidPackage {
1180            path: path.clone(),
1181            reason: format!(
1182                "installation is not ready: {error}; run `ml-runtime model doctor {}`",
1183                package
1184                    .parent()
1185                    .and_then(Path::file_name)
1186                    .and_then(|name| name.to_str())
1187                    .unwrap_or("MODEL")
1188            ),
1189        })?;
1190        serde_json::from_slice(&bytes).map_err(|error| AcquisitionError::InvalidPackage {
1191            path,
1192            reason: format!("invalid installation manifest: {error}"),
1193        })
1194    }
1195
1196    pub fn write_atomic(&self, package: &Path) -> Result<(), AcquisitionError> {
1197        let destination = package.join(INSTALLATION_MANIFEST_FILE);
1198        let temporary = package.join(format!(".{INSTALLATION_MANIFEST_FILE}.tmp"));
1199        let bytes = serde_json::to_vec_pretty(self)
1200            .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
1201        let mut output = fs::File::create(&temporary)
1202            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1203        output
1204            .write_all(&bytes)
1205            .and_then(|()| output.sync_all())
1206            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1207        fs::rename(&temporary, &destination)
1208            .map_err(|error| AcquisitionError::Io(error.to_string()))
1209    }
1210}
1211
1212#[derive(Clone, Debug, Default)]
1213pub struct BuiltinModelRegistry;
1214
1215impl BuiltinModelRegistry {
1216    pub fn list(&self) -> Vec<RegisteredModel> {
1217        vec![laya_registration()]
1218    }
1219
1220    pub fn resolve(&self, name: &str) -> Result<RegisteredModel, AcquisitionError> {
1221        self.list()
1222            .into_iter()
1223            .find(|model| model.name == name)
1224            .ok_or_else(|| {
1225                AcquisitionError::InvalidRequest(format!("unknown registered model {name:?}"))
1226            })
1227    }
1228}
1229
1230fn laya_registration() -> RegisteredModel {
1231    const REVISION: &str = "fff78b2d9750c6b748fe8c90fcbf8bed0a1522a9";
1232    let files = [
1233        (
1234            "coreml_config.json",
1235            "990b99a736f64c87da57b203d7953c4c1c79c18b615580db894e9c24bda42ab5",
1236        ),
1237        (
1238            "validation.json",
1239            "709e1a0ac95a7bf73df0b5a8582423c9f40c80a1b4edd3499a77a1ac2ac39731",
1240        ),
1241        (
1242            "encoder/config.json",
1243            "bf3ab80598fdccf414855a2ce80f22859e4492d06ca8a62ddd1cfb63972f8979",
1244        ),
1245        (
1246            "rl_agent_config.json",
1247            "ae287b56bbcf5f8c4f4541ae9dfd00c914c4c48b940b8398c3058af37ba92bbd",
1248        ),
1249        (
1250            "tokenizer/tokenizer.json",
1251            "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1252        ),
1253        (
1254            "tokenizer/tokenizer_config.json",
1255            "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1256        ),
1257        (
1258            "model.mlpackage/Manifest.json",
1259            "41bab6e532f727e8809c76906f41026a48ef9b276c56068b3d68270a13981e20",
1260        ),
1261        (
1262            "model.mlpackage/Data/com.apple.CoreML/model.mlmodel",
1263            "dc6a6383ad4a2f04f7525924b0dfb830429dedc44387f143a2f87782e39aeab0",
1264        ),
1265        (
1266            "model.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
1267            "5872b9f6530c20a845b69c0cb75aa141e9c89ffdd5f36529c3708cec9b7a7a83",
1268        ),
1269    ]
1270    .into_iter()
1271    .map(|(path, sha256)| RegisteredModelFile {
1272        path: path.to_owned(),
1273        sha256: sha256.to_owned(),
1274    })
1275    .collect();
1276    RegisteredModel {
1277        name: "laya".to_owned(),
1278        revision: REVISION.to_owned(),
1279        source: format!("https://huggingface.co/aac6fef/laya-coreml/resolve/{REVISION}"),
1280        backend: "coreml".to_owned(),
1281        runtime_requirement: ">=0.1.0".to_owned(),
1282        format: ModelFormat::CoreMl,
1283        artifact_path: "model.mlpackage".to_owned(),
1284        files,
1285    }
1286}
1287
1288pub fn default_model_root() -> Result<PathBuf, AcquisitionError> {
1289    if let Some(root) = std::env::var_os("ML_RUNTIME_MODEL_DIR") {
1290        return Ok(PathBuf::from(root));
1291    }
1292    #[cfg(target_os = "windows")]
1293    if let Some(root) = std::env::var_os("LOCALAPPDATA") {
1294        return Ok(PathBuf::from(root).join("ml-runtime/models"));
1295    }
1296    let home = std::env::var_os("HOME").ok_or_else(|| {
1297        AcquisitionError::InvalidRequest(
1298            "cannot determine model directory; set ML_RUNTIME_MODEL_DIR".to_owned(),
1299        )
1300    })?;
1301    #[cfg(target_os = "windows")]
1302    return Ok(PathBuf::from(home).join("AppData/Local/ml-runtime/models"));
1303    #[cfg(target_os = "macos")]
1304    return Ok(PathBuf::from(home).join("Library/Application Support/ml-runtime/models"));
1305    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
1306    Ok(PathBuf::from(home).join(".local/share/ml-runtime/models"))
1307}
1308
1309#[derive(Clone, Debug, PartialEq, Eq)]
1310pub struct RegisteredInstallResult {
1311    pub package_path: PathBuf,
1312    pub already_installed: bool,
1313}
1314
1315pub struct RegisteredModelInstaller {
1316    root: PathBuf,
1317    client: reqwest::Client,
1318    config: AcquisitionConfig,
1319}
1320
1321impl RegisteredModelInstaller {
1322    pub fn new(root: impl Into<PathBuf>) -> Result<Self, AcquisitionError> {
1323        let client = reqwest::Client::builder()
1324            .redirect(reqwest::redirect::Policy::limited(10))
1325            .build()
1326            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1327        Ok(Self {
1328            root: root.into(),
1329            client,
1330            config: AcquisitionConfig::default(),
1331        })
1332    }
1333
1334    pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
1335        self.config = config;
1336        self
1337    }
1338
1339    pub fn installed_path(&self, model: &RegisteredModel) -> PathBuf {
1340        self.root.join(&model.name).join(&model.revision)
1341    }
1342
1343    pub fn validate(
1344        &self,
1345        model: &RegisteredModel,
1346        package: &Path,
1347    ) -> Result<(), AcquisitionError> {
1348        let manifest =
1349            ModelPackage::open(package).map_err(|reason| AcquisitionError::InvalidPackage {
1350                path: package.to_path_buf(),
1351                reason,
1352            })?;
1353        let id = package_id(&manifest)?;
1354        let expected =
1355            ModelId::new(&model.name, &model.revision).map_err(AcquisitionError::Catalog)?;
1356        if id != expected || manifest.manifest.format != model.format {
1357            return Err(AcquisitionError::IdentityMismatch {
1358                requested: expected,
1359                found: id,
1360            });
1361        }
1362        if manifest.manifest.artifact.path != model.artifact_path {
1363            return Err(AcquisitionError::InvalidPackage {
1364                path: package.to_path_buf(),
1365                reason: format!(
1366                    "registered artifact path must be {:?}, got {:?}",
1367                    model.artifact_path, manifest.manifest.artifact.path
1368                ),
1369            });
1370        }
1371        if !runtime_requirement_satisfied(&model.runtime_requirement, env!("CARGO_PKG_VERSION")) {
1372            return Err(AcquisitionError::InvalidPackage {
1373                path: package.to_path_buf(),
1374                reason: format!(
1375                    "model requires runtime {}, current runtime is {}",
1376                    model.runtime_requirement,
1377                    env!("CARGO_PKG_VERSION")
1378                ),
1379            });
1380        }
1381        for file in &model.files {
1382            let path = safe_registered_path(package, &file.path)?;
1383            let actual = sha256_file_streaming(&path)?;
1384            if !actual.eq_ignore_ascii_case(&file.sha256) {
1385                return Err(AcquisitionError::InvalidPackage {
1386                    path,
1387                    reason: format!("sha256 mismatch: expected {}, got {actual}", file.sha256),
1388                });
1389            }
1390        }
1391        Ok(())
1392    }
1393
1394    pub async fn install(
1395        &self,
1396        model: &RegisteredModel,
1397        source_override: Option<&str>,
1398        mode: InstallMode,
1399        cancellation: Option<&CancellationToken>,
1400    ) -> Result<RegisteredInstallResult, AcquisitionError> {
1401        let final_path = self.installed_path(model);
1402        if final_path.exists() && mode == InstallMode::KeepExisting {
1403            self.validate(model, &final_path)?;
1404            return Ok(RegisteredInstallResult {
1405                package_path: final_path,
1406                already_installed: true,
1407            });
1408        }
1409        fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1410        let staging_root = self.root.join(".staging");
1411        fs::create_dir_all(&staging_root)
1412            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1413        let staging = staging_root.join(format!("{}-{}", model.name, std::process::id()));
1414        if staging.exists() {
1415            fs::remove_dir_all(&staging)
1416                .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1417        }
1418        fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1419        let source = source_override.unwrap_or(&model.source);
1420        let result = async {
1421            let mut downloaded = 0_u64;
1422            if source.starts_with("https://") || source.starts_with("http://") {
1423                validate_http_uri(source, false)?;
1424                for file in &model.files {
1425                    if cancellation.is_some_and(CancellationToken::is_cancelled) {
1426                        return Err(AcquisitionError::Cancelled);
1427                    }
1428                    let destination = safe_registered_path(&staging, &file.path)?;
1429                    if let Some(parent) = destination.parent() {
1430                        fs::create_dir_all(parent)
1431                            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1432                    }
1433                    self.download_file(
1434                        &format!("{}/{}", source.trim_end_matches('/'), file.path),
1435                        &destination,
1436                        &mut downloaded,
1437                        cancellation,
1438                    )
1439                    .await?;
1440                }
1441            } else {
1442                let source = Path::new(source);
1443                if !source.is_dir() {
1444                    return Err(AcquisitionError::InvalidRequest(format!(
1445                        "registered model source is not a directory: {}",
1446                        source.display()
1447                    )));
1448                }
1449                for file in &model.files {
1450                    let from = safe_registered_path(source, &file.path)?;
1451                    let to = safe_registered_path(&staging, &file.path)?;
1452                    if let Some(parent) = to.parent() {
1453                        fs::create_dir_all(parent)
1454                            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1455                    }
1456                    let size = fs::metadata(&from)
1457                        .map_err(|error| AcquisitionError::Io(error.to_string()))?
1458                        .len();
1459                    downloaded = downloaded.saturating_add(size);
1460                    if downloaded > self.config.max_download_bytes {
1461                        return Err(AcquisitionError::LimitExceeded {
1462                            limit: self.config.max_download_bytes,
1463                            actual: downloaded,
1464                        });
1465                    }
1466                    fs::copy(&from, &to)
1467                        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1468                }
1469            }
1470            write_registered_manifest(&staging, model)?;
1471            self.validate(model, &staging)?;
1472            let parent = final_path.parent().expect("registered model has parent");
1473            fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1474            if final_path.exists() {
1475                if mode != InstallMode::Replace {
1476                    return Err(AcquisitionError::AlreadyInstalled(
1477                        ModelId::new(&model.name, &model.revision)
1478                            .map_err(AcquisitionError::Catalog)?,
1479                    ));
1480                }
1481                let backup = parent.join(format!(".replace-{}", std::process::id()));
1482                fs::rename(&final_path, &backup)
1483                    .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1484                if let Err(error) = fs::rename(&staging, &final_path) {
1485                    let _ = fs::rename(&backup, &final_path);
1486                    return Err(AcquisitionError::Io(error.to_string()));
1487                }
1488                let _ = fs::remove_dir_all(backup);
1489            } else {
1490                fs::rename(&staging, &final_path)
1491                    .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1492            }
1493            Ok(RegisteredInstallResult {
1494                package_path: final_path.clone(),
1495                already_installed: false,
1496            })
1497        }
1498        .await;
1499        if staging.exists() {
1500            let _ = fs::remove_dir_all(staging);
1501        }
1502        result
1503    }
1504
1505    async fn download_file(
1506        &self,
1507        url: &str,
1508        destination: &Path,
1509        downloaded: &mut u64,
1510        cancellation: Option<&CancellationToken>,
1511    ) -> Result<(), AcquisitionError> {
1512        validate_http_uri(url, false)?;
1513        let mut response = tokio::time::timeout(
1514            std::time::Duration::from_secs(self.config.timeout_secs),
1515            self.client.get(url).send(),
1516        )
1517        .await
1518        .map_err(|_| AcquisitionError::Io(format!("download timed out: {url}")))?
1519        .map_err(|error| AcquisitionError::Io(error.to_string()))?
1520        .error_for_status()
1521        .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1522        let mut output = fs::File::create(destination)
1523            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1524        while let Some(chunk) = response
1525            .chunk()
1526            .await
1527            .map_err(|error| AcquisitionError::Io(error.to_string()))?
1528        {
1529            if cancellation.is_some_and(CancellationToken::is_cancelled) {
1530                return Err(AcquisitionError::Cancelled);
1531            }
1532            *downloaded = downloaded.saturating_add(chunk.len() as u64);
1533            if *downloaded > self.config.max_download_bytes {
1534                return Err(AcquisitionError::LimitExceeded {
1535                    limit: self.config.max_download_bytes,
1536                    actual: *downloaded,
1537                });
1538            }
1539            output
1540                .write_all(&chunk)
1541                .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1542        }
1543        output
1544            .sync_all()
1545            .map_err(|error| AcquisitionError::Io(error.to_string()))
1546    }
1547}
1548
1549fn safe_registered_path(root: &Path, relative: &str) -> Result<PathBuf, AcquisitionError> {
1550    let relative = Path::new(relative);
1551    if relative.is_absolute()
1552        || relative
1553            .components()
1554            .any(|component| !matches!(component, std::path::Component::Normal(_)))
1555    {
1556        return Err(AcquisitionError::InvalidRequest(
1557            "registered file path must remain inside the package".to_owned(),
1558        ));
1559    }
1560    Ok(root.join(relative))
1561}
1562
1563fn sha256_file_streaming(path: &Path) -> Result<String, AcquisitionError> {
1564    let mut file = fs::File::open(path).map_err(|error| AcquisitionError::InvalidPackage {
1565        path: path.to_path_buf(),
1566        reason: error.to_string(),
1567    })?;
1568    let mut digest = Sha256::new();
1569    let mut buffer = vec![0_u8; 8 * 1024 * 1024];
1570    loop {
1571        let count = file
1572            .read(&mut buffer)
1573            .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1574        if count == 0 {
1575            break;
1576        }
1577        digest.update(&buffer[..count]);
1578    }
1579    Ok(format!("{:x}", digest.finalize()))
1580}
1581
1582fn write_registered_manifest(
1583    destination: &Path,
1584    model: &RegisteredModel,
1585) -> Result<(), AcquisitionError> {
1586    let manifest = ModelManifest {
1587        schema_version: 1,
1588        id: model.name.clone(),
1589        model_version: Some(model.revision.clone()),
1590        version: None,
1591        format: model.format.clone(),
1592        artifact: ArtifactSpec {
1593            path: model.artifact_path.clone(),
1594            size_bytes: None,
1595            sha256: None,
1596        },
1597        metadata: BTreeMap::from([
1598            ("backend".to_owned(), model.backend.clone()),
1599            ("source".to_owned(), model.source.clone()),
1600            ("registry_revision".to_owned(), model.revision.clone()),
1601            (
1602                "runtime_requirement".to_owned(),
1603                model.runtime_requirement.clone(),
1604            ),
1605        ]),
1606        inputs: Vec::new(),
1607        outputs: Vec::new(),
1608    };
1609    fs::write(
1610        destination.join("manifest.json"),
1611        serde_json::to_vec_pretty(&manifest)
1612            .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?,
1613    )
1614    .map_err(|error| AcquisitionError::Io(error.to_string()))
1615}
1616
1617pub fn runtime_requirement_satisfied(requirement: &str, current: &str) -> bool {
1618    let Some(required) = requirement.strip_prefix(">=") else {
1619        return requirement == current || requirement == "*";
1620    };
1621    let key = |version: &str| {
1622        let mut parts = version
1623            .split('.')
1624            .map(|part| part.parse::<u64>().unwrap_or(0));
1625        (
1626            parts.next().unwrap_or(0),
1627            parts.next().unwrap_or(0),
1628            parts.next().unwrap_or(0),
1629        )
1630    };
1631    key(current) >= key(required)
1632}
1633
1634#[derive(Clone)]
1635pub struct ModelHandle {
1636    model_id: String,
1637    backend: String,
1638    format: ModelFormat,
1639    inner: Arc<dyn Any + Send + Sync>,
1640}
1641
1642impl ModelHandle {
1643    pub fn new(
1644        model_id: impl Into<String>,
1645        backend: impl Into<String>,
1646        format: ModelFormat,
1647        inner: Arc<dyn Any + Send + Sync>,
1648    ) -> Self {
1649        Self {
1650            model_id: model_id.into(),
1651            backend: backend.into(),
1652            format,
1653            inner,
1654        }
1655    }
1656
1657    pub fn id(&self) -> &str {
1658        &self.model_id
1659    }
1660
1661    pub fn backend(&self) -> &str {
1662        &self.backend
1663    }
1664
1665    pub fn format(&self) -> &ModelFormat {
1666        &self.format
1667    }
1668
1669    pub fn state<T: Any + Send + Sync>(&self) -> Option<&T> {
1670        self.inner.as_ref().downcast_ref::<T>()
1671    }
1672}
1673
1674impl std::fmt::Debug for ModelHandle {
1675    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1676        f.debug_struct("ModelHandle")
1677            .field("model_id", &self.model_id)
1678            .field("backend", &self.backend)
1679            .field("format", &self.format)
1680            .finish_non_exhaustive()
1681    }
1682}
1683
1684#[cfg(test)]
1685mod tests {
1686    use super::{
1687        ArtifactSpec, BuiltinModelRegistry, CompiledArtifactManifest, CompiledStatus,
1688        FilesystemModelCatalog, InstallMode, InstallationManifest, ModelCatalog, ModelFormat,
1689        ModelManifest, ModelReference, RegisteredModel, RegisteredModelFile,
1690        RegisteredModelInstaller,
1691    };
1692    use std::{fs, path::PathBuf};
1693
1694    #[test]
1695    fn accepts_lowercase_manifest_formats() {
1696        let manifest: ModelManifest = serde_json::from_str(
1697            r#"{"id":"example","format":"onnx","artifact":"artifacts/model.onnx"}"#,
1698        )
1699        .unwrap();
1700        assert_eq!(manifest.format, ModelFormat::Onnx);
1701    }
1702
1703    #[test]
1704    fn builtin_registry_pins_laya_distribution_metadata() {
1705        let laya = BuiltinModelRegistry.resolve("laya").unwrap();
1706        assert_eq!(laya.backend, "coreml");
1707        assert_eq!(laya.format, ModelFormat::CoreMl);
1708        assert_eq!(laya.artifact_path, "model.mlpackage");
1709        assert!(laya.source.contains(&laya.revision));
1710        assert!(laya
1711            .files
1712            .iter()
1713            .any(|file| file.path.ends_with("weights/weight.bin")));
1714        assert!(BuiltinModelRegistry.resolve("missing").is_err());
1715    }
1716
1717    #[test]
1718    fn installation_manifest_round_trips_atomically() {
1719        let root = std::env::temp_dir().join(format!(
1720            "ml-runtime-installation-manifest-{}",
1721            std::process::id()
1722        ));
1723        fs::create_dir_all(&root).unwrap();
1724        let manifest = InstallationManifest {
1725            schema_version: 1,
1726            model: "laya".to_owned(),
1727            model_revision: "revision".to_owned(),
1728            model_checksum: "model-hash".to_owned(),
1729            runtime_version: "0.1.0".to_owned(),
1730            runtime_requirement: ">=0.1.0".to_owned(),
1731            backend: "coreml".to_owned(),
1732            os: "macos".to_owned(),
1733            architecture: "aarch64".to_owned(),
1734            installed_at_unix_seconds: 1,
1735            compiled_status: CompiledStatus::Ready,
1736            compiled_artifact: Some(CompiledArtifactManifest {
1737                path: root.join("compiled.mlmodelc"),
1738                identity: "compiled-hash".to_owned(),
1739            }),
1740        };
1741        manifest.write_atomic(&root).unwrap();
1742        assert_eq!(InstallationManifest::read(&root).unwrap(), manifest);
1743        assert!(!root.join(".installation.json.tmp").exists());
1744        let _ = fs::remove_dir_all(root);
1745    }
1746
1747    #[tokio::test]
1748    async fn registered_installer_discovers_validates_and_rejects_corruption() {
1749        let root = std::env::temp_dir().join(format!(
1750            "ml-runtime-registered-install-{}",
1751            std::process::id()
1752        ));
1753        let source = root.join("source");
1754        let installed = root.join("installed");
1755        std::fs::create_dir_all(source.join("model.mlpackage")).unwrap();
1756        std::fs::write(source.join("config.json"), b"config").unwrap();
1757        std::fs::write(source.join("model.mlpackage/Manifest.json"), b"package").unwrap();
1758        let digest = |path: &std::path::Path| super::sha256_file_streaming(path).unwrap();
1759        let model = RegisteredModel {
1760            name: "fixture".to_owned(),
1761            revision: "revision-1".to_owned(),
1762            source: "https://example.invalid/fixture".to_owned(),
1763            backend: "coreml".to_owned(),
1764            runtime_requirement: ">=0.1.0".to_owned(),
1765            format: ModelFormat::CoreMl,
1766            artifact_path: "model.mlpackage".to_owned(),
1767            files: vec![
1768                RegisteredModelFile {
1769                    path: "config.json".to_owned(),
1770                    sha256: digest(&source.join("config.json")),
1771                },
1772                RegisteredModelFile {
1773                    path: "model.mlpackage/Manifest.json".to_owned(),
1774                    sha256: digest(&source.join("model.mlpackage/Manifest.json")),
1775                },
1776            ],
1777        };
1778        let installer = RegisteredModelInstaller::new(&installed).unwrap();
1779        let result = installer
1780            .install(
1781                &model,
1782                Some(source.to_str().unwrap()),
1783                InstallMode::KeepExisting,
1784                None,
1785            )
1786            .await
1787            .unwrap();
1788        assert_eq!(result.package_path, installed.join("fixture/revision-1"));
1789        assert!(result.package_path.join("manifest.json").is_file());
1790        installer.validate(&model, &result.package_path).unwrap();
1791
1792        let existing = installer
1793            .install(
1794                &model,
1795                Some(source.to_str().unwrap()),
1796                InstallMode::KeepExisting,
1797                None,
1798            )
1799            .await
1800            .unwrap();
1801        assert!(existing.already_installed);
1802        std::fs::write(existing.package_path.join("config.json"), b"corrupt").unwrap();
1803        assert!(installer.validate(&model, &existing.package_path).is_err());
1804        let _ = std::fs::remove_dir_all(root);
1805    }
1806
1807    #[test]
1808    fn accepts_artifact_integrity_metadata() {
1809        let manifest: ModelManifest = serde_json::from_str(
1810            r#"{"id":"example","format":"onnx","artifact":{"path":"model.onnx","size_bytes":3,"sha256":"abc"}}"#,
1811        )
1812        .unwrap();
1813        assert_eq!(
1814            manifest.artifact,
1815            ArtifactSpec {
1816                path: "model.onnx".to_owned(),
1817                size_bytes: Some(3),
1818                sha256: Some("abc".to_owned()),
1819            }
1820        );
1821    }
1822
1823    #[tokio::test]
1824    async fn discovers_and_resolves_existing_packages_deterministically() {
1825        let root = std::env::temp_dir().join(format!("ml-runtime-catalog-{}", std::process::id()));
1826        let first = root.join("nested/example-linear");
1827        fs::create_dir_all(first.join("artifacts")).unwrap();
1828        fs::write(
1829            first.join("manifest.json"),
1830            r#"{"id":"example-linear","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.json"}"#,
1831        )
1832        .unwrap();
1833        fs::write(first.join("artifacts/model.json"), "{}").unwrap();
1834
1835        let catalog = FilesystemModelCatalog::new(&root);
1836        let models = catalog.list().await.unwrap();
1837        assert_eq!(models[0].id.to_string(), "example-linear@1.0.0");
1838        let resolved = catalog
1839            .resolve(&ModelReference::id(
1840                "example-linear",
1841                Some("1.0.0".to_owned()),
1842            ))
1843            .await
1844            .unwrap();
1845        assert_eq!(resolved.package_path, PathBuf::from(&first));
1846        fs::remove_dir_all(root).unwrap();
1847    }
1848
1849    #[tokio::test]
1850    async fn installs_verified_package_atomically_and_refreshes_catalog() {
1851        use super::{
1852            AcquisitionConfig, FileModelSource, InstallMode, InstallResult, ModelFetchRequest,
1853            ModelId, ModelInstaller, ModelSourceReference,
1854        };
1855        use std::sync::Arc;
1856        let root = std::env::temp_dir().join(format!("ml-runtime-install-{}", std::process::id()));
1857        let source_root = root.join("source");
1858        let catalog_root = root.join("models");
1859        fs::create_dir_all(source_root.join("artifacts")).unwrap();
1860        fs::write(
1861            source_root.join("manifest.json"),
1862            r#"{"id":"acquired","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
1863        )
1864        .unwrap();
1865        fs::write(source_root.join("artifacts/model.bin"), b"model").unwrap();
1866
1867        let catalog = Arc::new(FilesystemModelCatalog::new(&catalog_root));
1868        let installer = ModelInstaller::new(&catalog_root)
1869            .with_catalog(Arc::clone(&catalog))
1870            .with_config(AcquisitionConfig {
1871                max_download_bytes: 1024,
1872                timeout_secs: 30,
1873            });
1874        let request = ModelFetchRequest {
1875            model: ModelId::new("acquired", "1.0.0").unwrap(),
1876            source: ModelSourceReference::Path(source_root.clone()),
1877        };
1878        let result = installer
1879            .install(
1880                &FileModelSource::new(),
1881                &request,
1882                InstallMode::KeepExisting,
1883                None,
1884            )
1885            .await
1886            .unwrap();
1887        assert!(matches!(result, InstallResult::Installed(_)));
1888        assert_eq!(catalog.list().await.unwrap().len(), 1);
1889        let existing = installer
1890            .install(
1891                &FileModelSource::new(),
1892                &request,
1893                InstallMode::KeepExisting,
1894                None,
1895            )
1896            .await
1897            .unwrap();
1898        assert!(matches!(existing, InstallResult::AlreadyInstalled(_)));
1899        assert!(!catalog_root
1900            .join(".staging")
1901            .join("acquired-1.0.0-")
1902            .exists());
1903        fs::remove_dir_all(root).unwrap();
1904    }
1905
1906    #[tokio::test]
1907    async fn rejects_identity_mismatch_without_catalog_entry() {
1908        use super::{
1909            FileModelSource, InstallMode, ModelFetchRequest, ModelId, ModelInstaller,
1910            ModelSourceReference,
1911        };
1912        use std::sync::Arc;
1913        let root = std::env::temp_dir().join(format!("ml-runtime-mismatch-{}", std::process::id()));
1914        let source = root.join("source");
1915        fs::create_dir_all(source.join("artifacts")).unwrap();
1916        fs::write(
1917            source.join("manifest.json"),
1918            r#"{"id":"other","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
1919        )
1920        .unwrap();
1921        fs::write(source.join("artifacts/model.bin"), b"model").unwrap();
1922        let catalog = Arc::new(FilesystemModelCatalog::new(root.join("models")));
1923        let installer = ModelInstaller::new(root.join("models")).with_catalog(Arc::clone(&catalog));
1924        let request = ModelFetchRequest {
1925            model: ModelId::new("requested", "1.0.0").unwrap(),
1926            source: ModelSourceReference::Path(source),
1927        };
1928        assert!(matches!(
1929            installer
1930                .install(
1931                    &FileModelSource::new(),
1932                    &request,
1933                    InstallMode::KeepExisting,
1934                    None
1935                )
1936                .await,
1937            Err(super::AcquisitionError::IdentityMismatch { .. })
1938        ));
1939        assert!(catalog.list().await.unwrap().is_empty());
1940        fs::remove_dir_all(root).unwrap();
1941    }
1942}