feat(open)!: detect the artifact format inside the viewer importer (#277)

Follow-up to #264 review (johanpel): let the analyzer detect the artifact's serialization format instead of threading it through `quent-open`.

`QuentViewer::import_events` and the `model!`-generated `import_events` now take just the context directory and detect the format from the on-disk streams (new `quent_exporter::FileSystemFormat::detect`). The server's `index_query_engines` detects per-context too. The generated viewer wrapper enables all exporter formats so any artifact opens, and `quent-open` drops `Format`/`detect_format` and the format component of its cache key.

**Breaking:** `QuentViewer::import_events` / `Model::import_events` drop the `format` argument; `index_query_engines` drops its `format` parameter. Downstream `QuentViewer` impls (e.g. sirius) drop the `format` param and call `Model::import_events(dir)`.

**Compatibility:** `quent-open` builds the wrapper against the quent/analyzer commits pinned in `model.qmi` and now emits the one-argument calls, so it can only open artifacts whose pinned commits already include this change. Artifacts pinned to earlier commits (from the pre-release window) won't build a viewer — an accepted consequence of this breaking change; versioning the sidecar/codegen against the pinned API is left as future work.

Off `main`, independent of the merged quent-open work (#265) and the open stack (#266/#273/#276). Whichever of this PR and that stack lands second needs a rebase — both touch `quent-open`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Authors:
  - Matthijs Brobbel (https://github.com/mbrobbel)

Approvers:
  - Johan Peltenburg (https://github.com/johanpel)

URL: #277

Author: mbrobbel

crates/exporter/src/lib.rs

@@ -111,6 +111,33 @@ impl TryFrom<&str> for FileSystemFormat {
     }
 }
 
+#[cfg(filesystem)]
+impl FileSystemFormat {
+    /// Detect the format of a context directory from the first recognized
+    /// `*.<ext>` event stream in any of its per-entity subdirectories. Returns
+    /// `None` if no readable stream with a known extension is present.
+    pub fn detect(context_dir: &std::path::Path) -> Option<Self> {
+        for entry in std::fs::read_dir(context_dir).ok()?.flatten() {
+            if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
+                continue;
+            }
+            let Ok(files) = std::fs::read_dir(entry.path()) else {
+                continue;
+            };
+            for file in files.flatten() {
+                if let Some(format) = std::path::Path::new(&file.file_name())
+                    .extension()
+                    .and_then(|ext| ext.to_str())
+                    .and_then(|ext| Self::try_from(ext).ok())
+                {
+                    return Some(format);
+                }
+            }
+        }
+        None
+    }
+}
+
 /// Options for exporting events to the filesystem in the given `format`, under
 /// the directory `root`, together with a `model.qmi` provenance sidecar.
 #[cfg(filesystem)]

crates/model-macros/src/model_macro.rs

@@ -341,10 +341,14 @@ pub fn expand(input: TokenStream) -> syn::Result<TokenStream> {
             #[doc = #doc_import]
             pub fn import_events(
                 dir: &std::path::Path,
-                format: quent_model::exporter::FileSystemFormat,
             ) -> quent_model::exporter::ImporterResult<
                 Box<dyn Iterator<Item = quent_model::Event<#event_type>>>,
             > {
+                // Detect the on-disk serialization format from the streams present;
+                // an empty/unrecognized context yields no events.
+                let Some(format) = quent_model::exporter::FileSystemFormat::detect(dir) else {
+                    return Ok(Box::new(std::iter::empty()));
+                };
                 let mut streams: Vec<
                     Box<dyn Iterator<Item = quent_model::Event<#event_type>>>,
                 > = Vec::new();

crates/open/src/error.rs

@@ -35,13 +35,6 @@ pub enum OpenError {
     )]
     NothingTrusted,
 
-    /// No recognized event stream extension was found, so the artifact format is
-    /// unknown.
-    #[error(
-        "could not determine the artifact format under '{root}': no ndjson, msgpack, or postcard event streams found"
-    )]
-    UnknownFormat { root: PathBuf },
-
     /// The sidecar lacks git remote/commit provenance needed to fetch a crate for
     /// the viewer build.
     #[error(

crates/open/src/lib.rs

@@ -62,7 +62,7 @@ use std::path::PathBuf;
 use quent_build_info::{ArtifactInfo, SIDECAR_FILE_NAME};
 
 pub use crate::error::{OpenError, Result};
-pub use crate::spec::{Format, GitPin, ViewerSpec, discover_contexts};
+pub use crate::spec::{GitPin, ViewerSpec, discover_contexts};
 pub use crate::trust::{Trust, canonicalize_remote};
 pub use crate::viewer::ViewerGroup;
 
@@ -115,7 +115,7 @@ pub async fn run(loader: impl Loader, options: OpenOptions) -> Result<()> {
 }
 
 /// Group `contexts` into one viewer per distinct build spec (same analyzer + pinned
-/// commits + format), gate each source on [trust](OpenOptions::trust), then build
+/// commits), gate each source on [trust](OpenOptions::trust), then build
 /// and serve the approved viewers in parallel. Contexts that can't be opened (no
 /// analyzer package, unreadable sidecar) are skipped with a warning rather than
 /// aborting.
@@ -134,7 +134,7 @@ pub async fn open(contexts: Vec<PathBuf>, options: OpenOptions) -> Result<()> {
                 path: context.join(SIDECAR_FILE_NAME),
                 source,
             })
-            .and_then(|info| ViewerSpec::from_artifact(&context, &info))
+            .and_then(|info| ViewerSpec::from_artifact(&info))
         {
             Ok(spec) => spec,
             Err(e) => {

crates/open/src/spec.rs

@@ -1,11 +1,11 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Build a [`ViewerSpec`] from a context's `model.qmi`: pinned git sources,
-//! analyzer package, and artifact format for generating/building a viewer.
+//! Build a [`ViewerSpec`] from a context's `model.qmi`: the pinned git sources
+//! and analyzer package needed to generate/build a viewer.
 
 use std::hash::{Hash, Hasher};
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 use quent_build_info::{ArtifactInfo, BuildInfo, SIDECAR_FILE_NAME};
 use walkdir::WalkDir;
@@ -67,43 +67,6 @@ fn is_hidden(entry: &walkdir::DirEntry) -> bool {
         .is_some_and(|name| name.starts_with('.'))
 }
 
-/// Serialization format of an artifact's event streams.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum Format {
-    Ndjson,
-    Msgpack,
-    Postcard,
-}
-
-impl Format {
-    /// File extension of an event stream in this format.
-    pub fn extension(self) -> &'static str {
-        match self {
-            Format::Ndjson => "ndjson",
-            Format::Msgpack => "msgpack",
-            Format::Postcard => "postcard",
-        }
-    }
-
-    /// The `quent_exporter::FileSystemFormat` variant name, for generated code.
-    pub fn variant(self) -> &'static str {
-        match self {
-            Format::Ndjson => "Ndjson",
-            Format::Msgpack => "Msgpack",
-            Format::Postcard => "Postcard",
-        }
-    }
-
-    fn from_extension(ext: &str) -> Option<Self> {
-        match ext {
-            "ndjson" => Some(Format::Ndjson),
-            "msgpack" => Some(Format::Msgpack),
-            "postcard" => Some(Format::Postcard),
-            _ => None,
-        }
-    }
-}
-
 /// A git source pinned to an exact commit, as recorded in the sidecar.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GitPin {
@@ -197,8 +160,6 @@ fn validate_package(package: &str) -> Result<()> {
 /// serve multiple same-spec contexts.
 #[derive(Debug, Clone)]
 pub struct ViewerSpec {
-    /// Event serialization format, detected from the on-disk streams.
-    pub format: Format,
     /// Cargo package of the analyzer crate providing `Viewer` (`QuentViewer`).
     pub analyzer_package: String,
     /// Quent framework source, pinned to the build commit.
@@ -208,8 +169,8 @@ pub struct ViewerSpec {
 }
 
 impl ViewerSpec {
-    /// Derive a spec from a sidecar and its context directory.
-    pub fn from_artifact(root: &Path, info: &ArtifactInfo) -> Result<Self> {
+    /// Derive a spec from a sidecar.
+    pub fn from_artifact(info: &ArtifactInfo) -> Result<Self> {
         let analyzer_package =
             info.model
                 .analyzer_package
@@ -219,7 +180,6 @@ impl ViewerSpec {
                 })?;
         validate_package(&analyzer_package)?;
         Ok(Self {
-            format: detect_format(root)?,
             analyzer_package,
             quent: GitPin::from_build_info(&info.quent, "quent")?,
             analyzer: GitPin::from_build_info(&info.model.source, "analyzer source")?,
@@ -232,29 +192,27 @@ impl ViewerSpec {
         self.analyzer_package.replace('-', "_")
     }
 
-    /// Unambiguous build identity: analyzer package, format, and both git
-    /// remotes + full commits. Used to group/dedup contexts into viewers.
-    /// Short label distinguishing this build from other groups (package, format,
-    /// and short pins) so concurrent viewers with equal context counts are
-    /// still tellable apart.
+    /// Short label distinguishing this build from other groups (package and short
+    /// pins) so concurrent viewers with equal context counts are still tellable
+    /// apart.
     pub fn describe(&self) -> String {
         format!(
-            "{} ({}, quent@{} analyzer@{})",
+            "{} (quent@{} analyzer@{})",
             self.analyzer_package,
-            self.format.extension(),
             short_commit(&self.quent.commit),
             short_commit(&self.analyzer.commit),
         )
     }
 
+    /// Unambiguous build identity: analyzer package and both git remotes + full
+    /// commits. Used to group/dedup contexts into viewers.
     pub fn group_key(&self) -> String {
         // Key on the Cargo-normalized remotes so equivalent spellings (e.g.
         // scp-style vs `ssh://`) — which produce one dependency — share a build
         // instead of splitting into separate viewers. Unit separator between
         // fields so values can't run together.
         [
             self.analyzer_package.as_str(),
-            self.format.extension(),
             self.quent.cargo_url().as_str(),
             &self.quent.commit,
             self.analyzer.cargo_url().as_str(),
@@ -270,10 +228,9 @@ impl ViewerSpec {
         let mut hasher = std::collections::hash_map::DefaultHasher::new();
         self.group_key().hash(&mut hasher);
         format!(
-            "{}-{}-{}-{:016x}",
+            "{}-{}-{:016x}",
             self.analyzer_package,
             short_commit(&self.analyzer.commit),
-            self.format.extension(),
             hasher.finish(),
         )
     }
@@ -285,36 +242,11 @@ fn short_commit(commit: &str) -> &str {
     &commit[..end]
 }
 
-/// Detect the artifact format from an `events.<ext>` stream in any per-entity
-/// subdirectory.
-fn detect_format(root: &Path) -> Result<Format> {
-    let entries = std::fs::read_dir(root).map_err(|source| OpenError::Sidecar {
-        path: root.to_path_buf(),
-        source,
-    })?;
-    for entry in entries.flatten() {
-        if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
-            continue;
-        }
-        if let Ok(files) = std::fs::read_dir(entry.path()) {
-            for file in files.flatten() {
-                if let Some(ext) = Path::new(&file.file_name()).extension()
-                    && let Some(format) = ext.to_str().and_then(Format::from_extension)
-                {
-                    return Ok(format);
-                }
-            }
-        }
-    }
-    Err(OpenError::UnknownFormat {
-        root: root.to_path_buf(),
-    })
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
     use quent_build_info::ModelInfo;
+    use std::path::Path;
 
     fn artifact_with(analyzer_package: Option<&str>, commit: &str) -> ArtifactInfo {
         let mut model = ModelInfo::unknown();
@@ -334,14 +266,6 @@ mod tests {
         info
     }
 
-    fn ctx_with_stream(name: &str, file: &str) -> tempfile::TempDir {
-        let dir = tempfile::tempdir().unwrap();
-        let entity = dir.path().join(name);
-        std::fs::create_dir_all(&entity).unwrap();
-        std::fs::write(entity.join(file), b"").unwrap();
-        dir
-    }
-
     fn make_context(dir: &Path) {
         std::fs::create_dir_all(dir.join("engine")).unwrap();
         std::fs::write(dir.join("engine").join("events.ndjson"), b"").unwrap();
@@ -407,7 +331,6 @@ mod tests {
     #[test]
     fn group_key_normalizes_equivalent_remotes() {
         let scp = ViewerSpec {
-            format: Format::Ndjson,
             analyzer_package: "p".into(),
             quent: GitPin {
                 remote: "git@github.com:org/quent.git".into(),
@@ -446,21 +369,6 @@ mod tests {
         assert_eq!(found.len(), 1);
     }
 
-    #[test]
-    fn detects_format_from_entity_subdir() {
-        let ctx = ctx_with_stream("engine", "events.msgpack");
-        assert_eq!(detect_format(ctx.path()).unwrap(), Format::Msgpack);
-    }
-
-    #[test]
-    fn unknown_format_when_no_streams() {
-        let ctx = ctx_with_stream("engine", "notes.txt");
-        assert!(matches!(
-            detect_format(ctx.path()),
-            Err(OpenError::UnknownFormat { .. })
-        ));
-    }
-
     #[test]
     fn validators_accept_good_and_reject_injection() {
         assert!(validate_commit("0123456789abcdef0123456789abcdef01234567").is_ok());
@@ -485,10 +393,9 @@ mod tests {
 
     #[test]
     fn spec_requires_analyzer_package() {
-        let ctx = ctx_with_stream("engine", "events.ndjson");
         let info = artifact_with(None, "abc");
         assert!(matches!(
-            ViewerSpec::from_artifact(ctx.path(), &info),
+            ViewerSpec::from_artifact(&info),
             Err(OpenError::NoAnalyzer { .. })
         ));
     }
@@ -515,34 +422,25 @@ mod tests {
 
     #[test]
     fn spec_derives_crate_ident_and_keys() {
-        let ctx = ctx_with_stream("engine", "events.ndjson");
         let info = artifact_with(Some("quent-simulator-analyzer"), "feedface99887766");
-        let spec = ViewerSpec::from_artifact(ctx.path(), &info).unwrap();
+        let spec = ViewerSpec::from_artifact(&info).unwrap();
         assert_eq!(spec.analyzer_crate(), "quent_simulator_analyzer");
-        assert_eq!(spec.format, Format::Ndjson);
         assert!(
             spec.cache_key()
-                .starts_with("quent-simulator-analyzer-feedface9988-ndjson-")
+                .starts_with("quent-simulator-analyzer-feedface9988-")
         );
     }
 
     #[test]
     fn keys_distinguish_full_pins_not_just_short_commit() {
-        let ctx = ctx_with_stream("engine", "events.ndjson");
-        // Same package, format, and 12-char commit prefix, but different full
-        // analyzer commits — must NOT collide.
-        let a =
-            ViewerSpec::from_artifact(ctx.path(), &artifact_with(Some("p"), "abcabcabcabc1111"))
-                .unwrap();
-        let b =
-            ViewerSpec::from_artifact(ctx.path(), &artifact_with(Some("p"), "abcabcabcabc2222"))
-                .unwrap();
+        // Same package and 12-char commit prefix, but different full analyzer
+        // commits — must NOT collide.
+        let a = ViewerSpec::from_artifact(&artifact_with(Some("p"), "abcabcabcabc1111")).unwrap();
+        let b = ViewerSpec::from_artifact(&artifact_with(Some("p"), "abcabcabcabc2222")).unwrap();
         assert_ne!(a.group_key(), b.group_key());
         assert_ne!(a.cache_key(), b.cache_key());
         // Identical inputs group together and are deterministic.
-        let a2 =
-            ViewerSpec::from_artifact(ctx.path(), &artifact_with(Some("p"), "abcabcabcabc1111"))
-                .unwrap();
+        let a2 = ViewerSpec::from_artifact(&artifact_with(Some("p"), "abcabcabcabc1111")).unwrap();
         assert_eq!(a.group_key(), a2.group_key());
         assert_eq!(a.cache_key(), a2.cache_key());
     }