feat(skippy): add Poolside Laguna staged-runtime candidate

crates/mesh-llm-commands/src/model_package.rs

@@ -77,6 +77,7 @@ pub async fn dispatch_model_package(args: ModelPrepareArgs<'_>) -> Result<()> {
     let source_model_ref = model_ref::ModelRef::parse(source_ref)
         .with_context(|| format!("invalid source model ref: {source_ref}"))?;
     let source_repo = source_model_ref.repo.as_str();
+    let source_revision = source_model_ref.revision.as_deref();
     let source_quant = match (source_model_ref.selector.as_deref(), quant) {
         (Some(selector), Some(quant)) if selector != quant => {
             bail!(
@@ -95,7 +96,7 @@ pub async fn dispatch_model_package(args: ModelPrepareArgs<'_>) -> Result<()> {
     // If no quant specified, list available quants and exit.
     // This path doesn't need HF_TOKEN — works for public repos.
     if source_quant.is_none() {
-        return run_list_quants(&hf_client, source_repo, json).await;
+        return run_list_quants(&hf_client, source_repo, source_revision, json).await;
     }
 
     let submitting = confirm && !dry_run;
@@ -116,6 +117,7 @@ pub async fn dispatch_model_package(args: ModelPrepareArgs<'_>) -> Result<()> {
     eprintln!("🔍 Resolving source...");
     let params = PrepareParams {
         source_repo: source_repo.to_string(),
+        source_revision: source_model_ref.revision.clone(),
         quant: source_quant.map(|s| s.to_string()),
         target: target.map(|s| s.to_string()),
         model_id: model_id.map(|s| s.to_string()),
@@ -254,15 +256,17 @@ pub async fn dispatch_model_package(args: ModelPrepareArgs<'_>) -> Result<()> {
 async fn run_list_quants(
     client: &hf_hub::HFClient,
     source_repo: &str,
+    source_revision: Option<&str>,
     json_output: bool,
 ) -> Result<()> {
-    let quants = prepare::list_quants(client, source_repo).await?;
+    let quants = prepare::list_quants(client, source_repo, source_revision).await?;
 
     if json_output {
         println!(
             "{}",
             serde_json::to_string_pretty(&json!({
                 "sourceRepo": source_repo,
+                "sourceRevision": source_revision,
                 "quants": quants,
             }))?
         );
@@ -280,13 +284,20 @@ async fn run_list_quants(
     eprintln!();
     eprintln!("Specify one as a model ref, e.g.:");
     eprintln!(
-        "   mesh-llm models package {}:{}",
-        source_repo, quants[0].name
+        "   mesh-llm models package {}",
+        source_quant_ref(source_repo, source_revision, &quants[0].name)
     );
 
     Ok(())
 }
 
+fn source_quant_ref(source_repo: &str, source_revision: Option<&str>, quant: &str) -> String {
+    source_revision.map_or_else(
+        || format!("{source_repo}:{quant}"),
+        |revision| format!("{source_repo}@{revision}:{quant}"),
+    )
+}
+
 fn print_quant_table(quants: &[DiscoveredQuant]) {
     // Find the longest name for alignment.
     let max_name = quants.iter().map(|q| q.name.len()).max().unwrap_or(0);
@@ -639,4 +650,20 @@ mod tests {
     fn parse_timeout_mixed() {
         assert_eq!(parse_timeout("1h30m45s").unwrap(), 5445);
     }
+
+    #[test]
+    fn source_quant_ref_preserves_revision() {
+        assert_eq!(
+            source_quant_ref("poolside/Laguna-S-2.1-GGUF", Some("abc123"), "Q4_K_M"),
+            "poolside/Laguna-S-2.1-GGUF@abc123:Q4_K_M"
+        );
+    }
+
+    #[test]
+    fn source_quant_ref_omits_absent_revision() {
+        assert_eq!(
+            source_quant_ref("poolside/Laguna-S-2.1-GGUF", None, "Q4_K_M"),
+            "poolside/Laguna-S-2.1-GGUF:Q4_K_M"
+        );
+    }
 }

crates/mesh-llm-host-runtime/src/inference/skippy/deployment.rs

@@ -125,7 +125,7 @@ pub(crate) fn stage0_config(
     };
     config.kv_cache = context
         .family_policy
-        .stage_kv_cache_config_for_stage(&config);
+        .stage_kv_cache_config_for_package(&config, &context.package.package_dir);
     config
 }
 

crates/mesh-llm-host-runtime/src/inference/skippy/family_policy.rs

@@ -50,6 +50,24 @@ impl FamilyPolicy {
     pub(crate) fn stage_kv_cache_config_for_stage(
         &self,
         config: &StageConfig,
+    ) -> Option<StageKvCacheConfig> {
+        self.stage_kv_cache_config_for_stage_with_meta(config, None)
+    }
+
+    pub(crate) fn stage_kv_cache_config_for_package(
+        &self,
+        config: &StageConfig,
+        package_dir: &Path,
+    ) -> Option<StageKvCacheConfig> {
+        let metadata_path = package_dir.join("shared/metadata.gguf");
+        let metadata = scan_gguf_compact_meta(&metadata_path);
+        self.stage_kv_cache_config_for_stage_with_meta(config, metadata.as_ref())
+    }
+
+    fn stage_kv_cache_config_for_stage_with_meta(
+        &self,
+        config: &StageConfig,
+        package_meta: Option<&GgufCompactMeta>,
     ) -> Option<StageKvCacheConfig> {
         match self.prefix_cache {
             FamilyPrefixCachePolicy::Disabled { .. } => None,
@@ -58,7 +76,7 @@ impl FamilyPolicy {
                 min_tokens,
                 max_entries,
             } => {
-                let max_bytes = derive_stage_cache_max_bytes(config)?;
+                let max_bytes = derive_stage_cache_max_bytes(config, package_meta)?;
                 // The family policy's `max_entries` is a generous
                 // upper bound on cache cardinality. The real ceiling
                 // is the unified KV cell pool size: each resident
@@ -316,18 +334,32 @@ fn wire_dtype_from_capability(dtype: WireDType) -> StageWireDType {
     }
 }
 
-fn derive_stage_cache_max_bytes(config: &StageConfig) -> Option<u64> {
+fn derive_stage_cache_max_bytes(
+    config: &StageConfig,
+    package_meta: Option<&GgufCompactMeta>,
+) -> Option<u64> {
+    if let Some(max_bytes) =
+        package_meta.and_then(|meta| estimate_stage_cache_max_bytes(config, meta))
+    {
+        return Some(max_bytes);
+    }
+
     [
         config.materialized_path.as_deref(),
         config.source_model_path.as_deref(),
         config.model_path.as_deref(),
     ]
     .into_iter()
     .flatten()
-    .find_map(|path| scan_gguf_compact_meta(Path::new(path)))
+    .find_map(|path| scan_stage_cache_meta(Path::new(path)))
     .and_then(|meta| estimate_stage_cache_max_bytes(config, &meta))
 }
 
+fn scan_stage_cache_meta(path: &Path) -> Option<GgufCompactMeta> {
+    scan_gguf_compact_meta(path)
+        .or_else(|| scan_gguf_compact_meta(&path.join("shared/metadata.gguf")))
+}
+
 fn estimate_stage_cache_max_bytes(config: &StageConfig, meta: &GgufCompactMeta) -> Option<u64> {
     let stage_layers = config.layer_end.checked_sub(config.layer_start)?;
     if stage_layers == 0 {
@@ -403,6 +435,8 @@ fn ggml_block_bytes(elements: u64, block_size: u64, type_size: u64) -> Option<u6
 
 #[cfg(test)]
 mod tests {
+    use std::fs;
+
     use super::*;
     use skippy_protocol::{FlashAttentionType, LoadMode};
     use skippy_topology::{STAGE_RUNTIME_LLAMA_FAMILY_EXPECTATIONS, reviewed_capability_records};
@@ -468,6 +502,42 @@ mod tests {
         }
     }
 
+    fn push_gguf_string(bytes: &mut Vec<u8>, value: &str) {
+        bytes.extend_from_slice(&(value.len() as u64).to_le_bytes());
+        bytes.extend_from_slice(value.as_bytes());
+    }
+
+    fn push_gguf_u32(bytes: &mut Vec<u8>, key: &str, value: u32) {
+        push_gguf_string(bytes, key);
+        bytes.extend_from_slice(&4u32.to_le_bytes());
+        bytes.extend_from_slice(&value.to_le_bytes());
+    }
+
+    fn push_gguf_string_kv(bytes: &mut Vec<u8>, key: &str, value: &str) {
+        push_gguf_string(bytes, key);
+        bytes.extend_from_slice(&8u32.to_le_bytes());
+        push_gguf_string(bytes, value);
+    }
+
+    fn write_package_metadata(package_dir: &Path) {
+        let mut bytes = Vec::new();
+        bytes.extend_from_slice(b"GGUF");
+        bytes.extend_from_slice(&2u32.to_le_bytes());
+        bytes.extend_from_slice(&0i64.to_le_bytes());
+        bytes.extend_from_slice(&8i64.to_le_bytes());
+        push_gguf_string_kv(&mut bytes, "general.architecture", "llama");
+        push_gguf_u32(&mut bytes, "llama.context_length", 8192);
+        push_gguf_u32(&mut bytes, "llama.embedding_length", 4096);
+        push_gguf_u32(&mut bytes, "llama.block_count", 32);
+        push_gguf_u32(&mut bytes, "llama.attention.head_count", 32);
+        push_gguf_u32(&mut bytes, "llama.attention.head_count_kv", 8);
+        push_gguf_u32(&mut bytes, "llama.attention.key_length", 128);
+        push_gguf_u32(&mut bytes, "llama.attention.value_length", 128);
+        let shared_dir = package_dir.join("shared");
+        fs::create_dir_all(&shared_dir).expect("create package shared directory");
+        fs::write(shared_dir.join("metadata.gguf"), bytes).expect("write package metadata");
+    }
+
     #[test]
     fn qwen_policy_comes_from_gguf_architecture() {
         let policy = family_policy_for_gguf_meta(&meta("qwen3"), None);
@@ -608,7 +678,7 @@ mod tests {
                 | "minicpm3" | "plamo" | "plamo3" | "plm" | "refact" | "smallthinker"
                 | "smollm3" | "arcee" | "chatglm" | "codeshell" | "deci" | "xverse" | "apertus"
                 | "bitnet" | "command_r" | "starcoder" | "ernie4_5" | "ernie4_5_moe" | "qwen"
-                | "jais" | "jais2" | "nemotron" | "llama4" | "mistral4" | "seed_oss" => {
+                | "jais" | "jais2" | "nemotron" | "llama4" | "mistral4" | "seed_oss" | "laguna" => {
                     assert_eq!(
                         policy.prefix_cache,
                         FamilyPrefixCachePolicy::Auto {
@@ -761,4 +831,29 @@ mod tests {
 
         assert!(estimate_stage_cache_max_bytes(&config, &kv_meta()).is_none());
     }
+
+    #[test]
+    fn package_metadata_enables_cache_for_remote_package_paths() {
+        let package_dir = tempfile::tempdir().expect("package directory");
+        write_package_metadata(package_dir.path());
+        let mut config = stage_config();
+        config.materialized_path = None;
+        config.source_model_path = Some("/source/not-downloaded/model.gguf".to_string());
+        config.model_path = Some("hf://mesh-llm/laguna-layers".to_string());
+        let policy = FamilyPolicy {
+            activation_wire_dtype: StageWireDType::F16,
+            prefix_cache: FamilyPrefixCachePolicy::Auto {
+                payload: FamilyPrefixCachePayload::ResidentKv,
+                min_tokens: 256,
+                max_entries: 16,
+            },
+        };
+
+        let cache = policy
+            .stage_kv_cache_config_for_package(&config, package_dir.path())
+            .expect("package metadata should provide the cache byte budget");
+
+        assert_eq!(cache.payload, StageKvCachePayload::ResidentKv);
+        assert_eq!(cache.max_bytes, 3_211_264);
+    }
 }

crates/mesh-llm-host-runtime/src/inference/skippy/resolver/native_mtp_tests.rs

@@ -34,6 +34,7 @@ fn native_mtp_generation() -> PackageGenerationInfo {
                 initial_window: 1,
                 min_window: 1,
                 max_window: 1,
+                pipeline_depth: None,
             }),
             proposer: Some("mtp".to_string()),
             primary: None,
@@ -89,6 +90,7 @@ fn native_mtp_cache_generation() -> PackageGenerationInfo {
                 initial_window: 2,
                 min_window: 1,
                 max_window: 6,
+                pipeline_depth: None,
             }),
             proposer: None,
             primary: Some("mtp".to_string()),
@@ -131,6 +133,7 @@ fn ngram_cache_generation() -> PackageGenerationInfo {
                 initial_window: 6,
                 min_window: 1,
                 max_window: 6,
+                pipeline_depth: None,
             }),
             proposer: Some("cache".to_string()),
             primary: None,
@@ -173,6 +176,7 @@ fn ngram_suffix_generation() -> PackageGenerationInfo {
                 initial_window: 32,
                 min_window: 1,
                 max_window: 32,
+                pipeline_depth: Some(2),
             }),
             proposer: Some("suffix".to_string()),
             primary: None,
@@ -239,6 +243,7 @@ fn speculative_strategy_auto_detects_direct_gguf_native_mtp_tensors() {
 
     assert_eq!(resolved.speculative.strategy, "auto");
     assert!(resolved.speculative.native_mtp_enabled);
+    assert_eq!(resolved.speculative.decode.verify_window.pipeline_depth, 1);
     let load_options = resolved
         .to_model_load_options(SkippyTelemetryOptions::off())
         .expect("model load options should build");
@@ -451,12 +456,7 @@ strategy = "ngram-cache"
 
 #[test]
 fn package_suffix_strategy_resolves_as_a_standalone_proposer() {
-    let mesh_config = parse_config(
-        r#"
-[defaults.speculative]
-strategy = "ngram-suffix"
-"#,
-    );
+    let mesh_config = parse_config("");
     let model_file = temp_model_file();
     let generation = ngram_suffix_generation();
 
@@ -476,10 +476,12 @@ strategy = "ngram-suffix"
         resolved.speculative.decode.effective_strategy,
         "ngram-suffix"
     );
+    assert_eq!(resolved.speculative.decode.verify_window.pipeline_depth, 2);
     let openai = resolved
         .to_embedded_openai_args(4096, true)
         .expect("package suffix strategy should build OpenAI args");
     assert_eq!(openai.speculative_window, 48);
+    assert_eq!(openai.speculative.verify_window.pipeline_depth, 2);
     assert_eq!(
         openai.speculative.ngram.as_ref().map(|ngram| ngram.kind),
         Some(skippy_server::NgramProposerKind::Suffix)

crates/mesh-llm-host-runtime/src/inference/skippy/resolver/speculative.rs

@@ -563,7 +563,7 @@ fn verify_window_config(policy: &PackageWindowPolicyInfo) -> VerifyWindowConfig
     VerifyWindowConfig {
         min_tokens: policy.min_window as usize,
         max_tokens: policy.max_window as usize,
-        pipeline_depth: 1,
+        pipeline_depth: policy.pipeline_depth.unwrap_or(1) as usize,
     }
 }
 

crates/mesh-llm-host-runtime/src/inference/skippy/stage/mod.rs

@@ -1,6 +1,7 @@
 use std::{
     collections::HashMap,
     net::SocketAddr,
+    path::Path,
     sync::{
         Arc,
         atomic::{AtomicBool, Ordering},
@@ -738,7 +739,12 @@ fn stage_config(
         downstream: load.downstream.as_ref().map(peer_config),
     };
     let family_policy = super::family_policy_for_stage_config(&config);
-    config.kv_cache = family_policy.stage_kv_cache_config_for_stage(&config);
+    config.kv_cache = package.map_or_else(
+        || family_policy.stage_kv_cache_config_for_stage(&config),
+        |package| {
+            family_policy.stage_kv_cache_config_for_package(&config, Path::new(&package.local_ref))
+        },
+    );
     Ok(config)
 }
 

crates/model-package/src/bin/queue-unsloth-layer-packages.rs

@@ -685,7 +685,7 @@ async fn build_candidate(
         return Ok(None);
     }
 
-    let quants = match prepare::list_quants(client, &model.repo_id).await {
+    let quants = match prepare::list_quants(client, &model.repo_id, None).await {
         Ok(quants) => quants,
         Err(err) => {
             eprintln!(
@@ -1096,12 +1096,14 @@ fn job_spec_with_token(
             JobVolume {
                 volume_type: "bucket".into(),
                 source: "meshllm/layer-split-output".into(),
+                revision: None,
                 mount_path: "/bucket".into(),
                 read_only: None,
             },
             JobVolume {
                 volume_type: "model".into(),
                 source: candidate.model.repo_id.clone(),
+                revision: Some("main".into()),
                 mount_path: "/source".into(),
                 read_only: Some(true),
             },