feat(metadata): declare how an encoder batches, and check that it can

crates/onnx-genai-comfyui-config/src/lib.rs

@@ -229,7 +229,11 @@ pub fn convert(
     }
     let document = lowering.build(adapters.as_ref().map(|(value, _)| value))?;
 
-    let metadata: InferenceMetadata = serde_json::from_value(document.clone())?;
+    // Through the shared entry point, not `serde` directly: a lowering that
+    // built its own document is exactly as capable of stamping a version it does
+    // not mean as a file on disk is.
+    let metadata: InferenceMetadata = onnx_genai_metadata::parse_metadata_json(&document)
+        .map_err(|error| ComfyUiConfigError::InvalidMetadata(error.to_string()))?;
     onnx_genai_metadata::validate_metadata(&metadata)
         .map_err(|errors| ComfyUiConfigError::InvalidMetadata(errors.join("; ")))?;
 

crates/onnx-genai-comfyui-config/src/lower.rs

@@ -98,7 +98,10 @@ impl<'a> Lowering<'a> {
         workflow.insert("steps".to_owned(), Value::Array(steps));
 
         let mut document = Map::new();
-        document.insert("schema_version".to_owned(), json!("v1"));
+        document.insert(
+            "schema_version".to_owned(),
+            json!(onnx_genai_metadata::SCHEMA_VERSION),
+        );
         document.insert(
             "pipeline".to_owned(),
             json!({ "workflow": Value::Object(workflow) }),

crates/onnx-genai-engine/src/bin/migrate_model_io.rs

@@ -204,7 +204,7 @@ fn migrate(
     let rendered = format!("{HEADER}{}", serde_yaml::to_string(&document)?);
     // Parse the result back through the real schema before writing. A tool that
     // emits a package the runtime rejects is worse than no tool.
-    let parsed: onnx_genai_metadata::InferenceMetadata = serde_yaml::from_str(&rendered)?;
+    let parsed = onnx_genai_metadata::parse_metadata(&rendered, Some("yaml"))?;
     onnx_genai_metadata::validation::validate_metadata(&parsed)
         .map_err(|errors| format!("converted package does not validate: {errors:#?}"))?;
     std::fs::write(&path, rendered)?;

crates/onnx-genai-engine/src/engine/metadata.rs

@@ -672,6 +672,7 @@ pub fn graph_port_contracts(
                 shape: None,
                 optional: false,
                 batch_layout: onnx_genai_metadata::BatchLayout::RequestAligned { axis: 0 },
+                padding: Vec::new(),
             },
         );
     }

crates/onnx-genai-engine/src/pipeline/generation.rs

@@ -1123,9 +1123,14 @@ fn test_decoder_runtime_inner(shape: TestSessionShape) -> anyhow::Result<Workflo
         // runtime behaviour over a document shape `validate_pipeline_spec`
         // refuses. A fixture that cannot be loaded is a weak premise for a
         // test about what happens once it is.
-        onnx_genai_metadata::validate_pipeline_spec(&onnx_genai_metadata::PipelineSpec {
-            workflow: workflow.clone(),
-        })
+        onnx_genai_metadata::validate_pipeline_spec(
+            &onnx_genai_metadata::PipelineSpec {
+                workflow: workflow.clone(),
+            },
+            // A workflow this crate builds today is a document written today, so
+            // it is held to everything the newest schema version asks for.
+            onnx_genai_metadata::SUPPORTED_SCHEMA_VERSION,
+        )
         .map_err(|error| anyhow::anyhow!("the fixture package must validate: {error:?}"))?;
     }
     validate_generation_workflow(&workflow)?;

crates/onnx-genai-engine/src/pipeline/islands.rs

@@ -1157,6 +1157,7 @@ fn session_tensor_contract(
         shape: Some(shape),
         optional: false,
         batch_layout: onnx_genai_metadata::BatchLayout::Shared,
+        padding: Vec::new(),
     }
 }
 
@@ -2369,6 +2370,7 @@ mod tests {
             effects: Vec::new(),
             row_scope: None,
             cache_affects_state: Default::default(),
+            batch_capacity: None,
         }
     }
 
@@ -2386,6 +2388,7 @@ mod tests {
             ),
             optional: false,
             batch_layout: onnx_genai_metadata::BatchLayout::RequestAligned { axis: 0 },
+            padding: Vec::new(),
         }
     }
 
@@ -2396,6 +2399,7 @@ mod tests {
             shape: Some(vec![onnx_genai_metadata::TensorDimension::Fixed(1)]),
             optional: false,
             batch_layout: onnx_genai_metadata::BatchLayout::Shared,
+            padding: Vec::new(),
         }
     }
 

crates/onnx-genai-engine/src/pipeline/workflow.rs

@@ -5706,6 +5706,7 @@ mod workflow_sampling_binding_tests {
             shape: None,
             optional: false,
             batch_layout: BatchLayout::default(),
+            padding: Vec::new(),
         };
 
         let value = workflow_request_value(&RuntimeInputRole::PromptTokens, &request, &contract)
@@ -5728,6 +5729,7 @@ mod workflow_sampling_binding_tests {
             shape: None,
             optional: false,
             batch_layout: BatchLayout::default(),
+            padding: Vec::new(),
         };
 
         let error =
@@ -5750,6 +5752,7 @@ mod workflow_sampling_binding_tests {
             shape: Some(vec![TensorDimension::Fixed(1)]),
             optional: false,
             batch_layout: BatchLayout::default(),
+            padding: Vec::new(),
         };
 
         let top_k = workflow_request_value(&RuntimeInputRole::SamplingTopK, &request, &contract)
@@ -5936,7 +5939,7 @@ pub(crate) struct WorkflowLoopPlan<'n> {
     pub(crate) continue_when: &'n str,
     pub(crate) max_iterations: &'n str,
     pub(crate) termination: &'n onnx_genai_metadata::WorkflowLoopTermination,
-    pub(crate) iteration: &'n Option<onnx_genai_metadata::WorkflowLoopIteration>,
+    pub(crate) iteration: &'n Option<Box<onnx_genai_metadata::WorkflowLoopIteration>>,
     pub(crate) carried: &'n [onnx_genai_metadata::WorkflowLoopCarry],
 }
 

crates/onnx-genai-genai-config/src/compatibility.rs

@@ -849,6 +849,7 @@ fn port_contracts_from_graph(
                     shape: None,
                     optional: false,
                     batch_layout: onnx_genai_metadata::BatchLayout::RequestAligned { axis: 0 },
+                    padding: Vec::new(),
                 },
             )
         })

crates/onnx-genai-metadata/src/decoder_workflow.rs

@@ -383,6 +383,7 @@ pub fn decoder_workflow(
         effects: Vec::new(),
         row_scope: None,
         cache_affects_state: BTreeSet::new(),
+        batch_capacity: None,
     };
 
     for (cell, port, contract, default) in [
@@ -429,6 +430,7 @@ pub fn decoder_workflow(
         effects: Vec::new(),
         row_scope: None,
         cache_affects_state: BTreeSet::new(),
+        batch_capacity: None,
     };
 
     let mut body = vec![
@@ -558,10 +560,10 @@ pub fn decoder_workflow(
             // special case.
             termination: crate::schema::WorkflowLoopTermination::GenerationEos,
             carried,
-            iteration: Some(crate::schema::WorkflowLoopIteration {
+            iteration: Some(Box::new(crate::schema::WorkflowLoopIteration {
                 value: LOOP_ITERATION.to_string(),
                 contract: scalar_contract(),
-            }),
+            })),
         }],
     };
     Ok(spec)
@@ -682,6 +684,7 @@ pub fn iteration_variant(
             },
         ),
         cache_affects_state: decoder.cache_affects_state.clone(),
+        batch_capacity: None,
     };
 
     let component = policy.component().to_string();
@@ -977,6 +980,7 @@ impl Builder {
                     )]),
                     optional: false,
                     batch_layout: BatchLayout::Shared,
+                    padding: Vec::new(),
                 },
                 role: SemanticInputRole::Runtime {
                     version: CONTRACT_VERSION.to_string(),
@@ -1401,6 +1405,7 @@ fn token_contract() -> TensorContract {
         shape: dims(&["batch", "sequence"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1411,6 +1416,7 @@ fn mask_contract() -> TensorContract {
         shape: dims(&["batch", "kv_sequence"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1421,6 +1427,7 @@ fn logits_contract() -> TensorContract {
         shape: dims(&["batch", "sequence", "vocabulary"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1431,6 +1438,7 @@ fn hidden_contract() -> TensorContract {
         shape: dims(&["batch", "sequence", "hidden"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1441,6 +1449,7 @@ fn state_contract() -> TensorContract {
         shape: dims(&["batch", "kv_heads", "kv_sequence", "head_dim"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1451,6 +1460,7 @@ fn lengths_contract() -> TensorContract {
         shape: dims(&["batch"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1461,6 +1471,7 @@ fn flag_contract() -> TensorContract {
         shape: dims(&["batch"]),
         optional: false,
         batch_layout: request_aligned(),
+        padding: Vec::new(),
     }
 }
 
@@ -1471,6 +1482,7 @@ fn scalar_contract() -> TensorContract {
         shape: Some(vec![crate::schema::TensorDimension::Fixed(1)]),
         optional: false,
         batch_layout: BatchLayout::Shared,
+        padding: Vec::new(),
     }
 }
 

crates/onnx-genai-metadata/src/lib.rs

@@ -2,9 +2,17 @@
 //!
 //! Implements the spec from <https://github.com/onnx/onnx/issues/8184>
 
-/// Current inference-metadata schema version. Emitters should stamp this into
-/// [`schema::InferenceMetadata::schema_version`]; readers treat an absent value
-/// as this version.
+/// The spelling of the base schema version that emitters stamp.
+///
+/// It stays `v1` because that is what every writer in this repository already
+/// stamps and what 19 in-tree documents already say. Readers normalize the
+/// spellings in the wild — absent, `v1`, `1`, `1.0` — onto
+/// [`INITIAL_SCHEMA_VERSION`], so changing what is emitted would rewrite bytes
+/// and semantic identities to say something no reader distinguishes.
+///
+/// A package that uses a field a later version introduced states that later
+/// version instead, and must: see [`version`] and
+/// [`BATCHING_SCHEMA_VERSION`].
 pub const SCHEMA_VERSION: &str = "v1";
 
 /// Built-in serialized capability identifiers.
@@ -108,6 +116,7 @@ pub mod parser;
 pub mod schema;
 pub mod session_state;
 pub mod validation;
+pub mod version;
 
 pub use cache::{CacheDependencies, cache_dependencies};
 pub use decoder_abi::decoder_abi;
@@ -121,7 +130,7 @@ pub use parser::{
     MtpProposerSpec, SpeculatorConfigSource, SpeculatorDescriptor, SpeculatorProposerKind,
     SpeculatorProposerStatus, detect_speculator, find_metadata_path, load_metadata,
     load_metadata_from_dir, load_metadata_package, load_metadata_with_identity, load_pipeline_spec,
-    resolve_package_artifact,
+    parse_metadata, parse_metadata_json, resolve_package_artifact,
 };
 pub use schema::*;
 pub use session_state::{
@@ -131,6 +140,9 @@ pub use validation::{
     CapabilityReport, PipelineValidationError, RuntimeCapabilities, derived_capabilities, validate,
     validate_metadata, validate_pipeline_spec, validate_structure_and_capabilities,
 };
+pub use version::{
+    BATCHING_SCHEMA_VERSION, INITIAL_SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSION, SchemaVersion,
+};
 
 /// Generates the inference-metadata JSON Schema with deterministic object-key ordering.
 pub fn inference_metadata_schema_json() -> Result<String, serde_json::Error> {