feat(rust): add schema-aware incremental item writer (#127)

.agents/skills/polyxml-codegen-workflow/SKILL.md

@@ -1008,3 +1008,17 @@ checkout because the helper builds with that cwd. The generated-model test
 helper now honors this override and builds the matching CLI if needed. Keep
 workspace targets owned by one worktree; switching checkouts in a shared target
 can leave stale unchanged executables even after a core compile message.
+
+### Incremental Rust producer verification (#127)
+
+For the generated `write_<root>_items` producer, build the CLI then run
+`.venv/bin/python scripts/verify_incremental_writer.py` (requires lxml and GNU
+`time`). It compiles owned/borrowed generated models, checks occurrence errors
+and sink failures, validates XML with libxml2, and records fresh-process RSS.
+Use `--output` to retain raw samples. Ordinary `encode_xml` streams an existing
+model; this producer consumes owned items from an iterator without a root Vec.
+Eligibility must use `upa::Document` source QNames: flattened FieldDef namespace
+metadata does not preserve every local `form`/`elementFormDefault` distinction.
+Expose the API only for plain sequence roots with one repeated field and item
+codecs whose element namespaces match the root. Keep unsupported schema shapes
+out of the API rather than claiming full streaming schema support.

crates/polyxml-core/src/codegen/rust/mod.rs

@@ -1940,6 +1940,136 @@ impl RustCodegen {
         out.push_str("    }\n");
 
         out.push_str("}\n");
+        self.emit_incremental_roots(out, s, ir, types_with_lifetime);
+    }
+
+    /// Only expose the producer API where ordinary item codecs preserve the schema.
+    fn emit_incremental_roots(
+        &self,
+        out: &mut String,
+        s: &StructDef,
+        ir: &SchemaIR,
+        lifetimes: &HashSet<QName>,
+    ) {
+        fn supported(
+            s: &StructDef,
+            ir: &SchemaIR,
+            namespace: &Option<String>,
+            seen: &mut HashSet<QName>,
+        ) -> bool {
+            if ir
+                .upa_documents
+                .iter()
+                .find_map(|doc| doc.uniform_sequence(&s.qname, namespace))
+                != Some(true)
+            {
+                return false;
+            }
+            if !seen.insert(s.qname.clone()) {
+                return false;
+            }
+            if s.base_type.is_some()
+                || s.is_abstract
+                || s.is_mixed
+                || ir.ordered_types.contains(&s.qname)
+            {
+                return false;
+            }
+            if ir
+                .content_models
+                .get(&s.qname)
+                .is_some_and(|p| p.has_choice() || p.has_reference() || p.has_repeated_sequence())
+            {
+                return false;
+            }
+            s.fields.iter().all(|f| {
+                if f.nillable
+                    || f.is_cycle_cut
+                    || f.xml_name.contains(':')
+                    || f.type_ref.is_list()
+                    || f.type_ref.is_boxed()
+                {
+                    return false;
+                }
+                match f.kind {
+                    FieldKind::Element if &f.namespace != namespace => return false,
+                    FieldKind::Attribute if f.namespace.is_some() => return false,
+                    FieldKind::Element | FieldKind::Attribute | FieldKind::Text => {}
+                    _ => return false,
+                }
+                match &f.type_ref {
+                    TypeRef::Named(q) => match ir.types.get(q) {
+                        Some(TypeDef::Struct(child)) => {
+                            supported(child, ir, namespace, &mut seen.clone())
+                        }
+                        Some(TypeDef::Enum(_)) => true,
+                        _ => false,
+                    },
+                    TypeRef::Primitive(_) => true,
+                    _ => false,
+                }
+            })
+        }
+        if s.fields.len() != 1
+            || s.fields[0].kind != FieldKind::Element
+            || !s.fields[0].cardinality.is_list()
+        {
+            return;
+        }
+        let field = &s.fields[0];
+        let mut methods = HashSet::new();
+        for root in ir.elements.values() {
+            if root.type_ref != TypeRef::Named(s.qname.clone())
+                || root.nillable
+                || !supported(s, ir, &root.qname.namespace, &mut HashSet::new())
+            {
+                continue;
+            }
+            let name = type_ident(&s.qname);
+            let item_type = self.format_rust_type_ref(&field.type_ref, lifetimes);
+            let impl_type = if self.options.zero_copy && lifetimes.contains(&s.qname) {
+                format!("impl<'a> {name}<'a>")
+            } else {
+                format!("impl {name}")
+            };
+            let base_method = format!("write_{}_items", AsSnakeCase(&root.qname.local));
+            let mut method = base_method.clone();
+            let mut suffix = 2;
+            while !methods.insert(method.clone()) {
+                method = format!("{base_method}_{suffix}");
+                suffix += 1;
+            }
+            writeln!(out, "\n{impl_type} {{").unwrap();
+            out.push_str("    /// Produce a document incrementally, retaining only the current item.\n    /// Errors may leave partial XML in the sink; publish files only after success.\n");
+            writeln!(out, "    pub fn {method}<W: std::io::Write, I: IntoIterator<Item = {item_type}>>(sink: &mut W, items: I) -> Result<()> {{").unwrap();
+            out.push_str("        let writer = &mut Writer::new(sink);\n");
+            writeln!(
+                out,
+                "        let {}start = BytesStart::new({:?});",
+                if root.qname.namespace.is_some() {
+                    "mut "
+                } else {
+                    ""
+                },
+                root.qname.local
+            )
+            .unwrap();
+            if let Some(ns) = &root.qname.namespace {
+                writeln!(out, "        start.push_attribute((\"xmlns\", {ns:?}));").unwrap();
+            }
+            out.push_str("        writer.write_event(Event::Start(start))?;\n        let mut count = 0usize;\n");
+            let mut checks = String::new();
+            if let crate::ir::OccursLimit::Count(max) = field.cardinality.max_occurs {
+                writeln!(checks, "            if count == {max} {{ return Err(PolyXmlError::SchemaError(\"maxOccurs exceeded\".into())); }}").unwrap();
+            }
+            checks.push_str("            count = count.checked_add(1).ok_or_else(|| PolyXmlError::SchemaError(\"item count overflow\".into()))?;\n");
+            self.emit_pattern_check(&mut checks, field, "&item.to_string()", ir);
+            self.emit_element_serialize_from(out, field, "items", ir, Some("items"), &checks);
+            if field.cardinality.min_occurs > 0 {
+                writeln!(out, "        if count < {} {{ return Err(PolyXmlError::SchemaError(\"minOccurs not satisfied\".into())); }}", field.cardinality.min_occurs).unwrap();
+            }
+            writeln!(out, "        writer.write_event(Event::End(BytesEnd::new({:?})))?;\n        Ok(())\n    }}\n}}", root.qname.local).unwrap();
+        }
     }
 
     fn emit_integer_bounds(
@@ -2406,6 +2536,18 @@ impl RustCodegen {
         field: &FieldDef,
         rust_name: &str,
         ir: &SchemaIR,
+    ) {
+        self.emit_element_serialize_from(out, field, rust_name, ir, None, "");
+    }
+
+    fn emit_element_serialize_from(
+        &self,
+        out: &mut String,
+        field: &FieldDef,
+        rust_name: &str,
+        ir: &SchemaIR,
+        source: Option<&str>,
+        before_item: &str,
     ) {
         let is_list = field.cardinality.is_list() || field.type_ref.is_list();
         let is_optional = field.cardinality.is_optional() || field.nillable;
@@ -2415,7 +2557,11 @@ impl RustCodegen {
         let is_enum = self.field_is_enum(&field.type_ref, ir).is_some();
 
         if is_list {
-            let _ = writeln!(out, "        for item in &self.{} {{", rust_name);
+            let source = source
+                .map(str::to_owned)
+                .unwrap_or_else(|| format!("&self.{rust_name}"));
+            let _ = writeln!(out, "        for item in {source} {{");
+            out.push_str(before_item);
             if is_string {
                 let _ = writeln!(
                     out,

crates/polyxml-core/src/schema_parser/upa.rs

@@ -15,6 +15,8 @@ pub struct Document {
     groups: BTreeMap<QName, Model>,
     named: BTreeMap<QName, Model>,
     anonymous: Vec<(String, Model)>,
+    #[serde(default)]
+    unsupported_attribute_types: BTreeSet<QName>,
 }
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 enum Model {
@@ -115,29 +117,15 @@ fn node(
                 Event::Start(child)
                     if matches!(
                         strip_prefix(child.name().into_inner()),
-                        "annotation"
-                            | "simpleType"
-                            | "attribute"
-                            | "attributeGroup"
-                            | "anyAttribute"
-                            | "unique"
-                            | "key"
-                            | "keyref"
+                        "annotation" | "simpleType" | "unique" | "key" | "keyref"
                     ) =>
                 {
                     reader.read_to_end(child.name())?;
                 }
                 Event::Empty(child)
                     if matches!(
                         strip_prefix(child.name().into_inner()),
-                        "annotation"
-                            | "simpleType"
-                            | "attribute"
-                            | "attributeGroup"
-                            | "anyAttribute"
-                            | "unique"
-                            | "key"
-                            | "keyref"
+                        "annotation" | "simpleType" | "unique" | "key" | "keyref"
                     ) => {}
                 Event::Start(child) => {
                     result
@@ -256,6 +244,28 @@ fn particle(node: &Node, ns: Option<&str>, qualified: bool) -> Option<Model> {
     Some(repeat(node, model))
 }
 impl Document {
+    /// Whether a named type has plain sequence content in one element namespace.
+    /// Source QNames retain local `form` and `elementFormDefault` distinctions.
+    pub(crate) fn uniform_sequence(
+        &self,
+        name: &QName,
+        namespace: &Option<String>,
+    ) -> Option<bool> {
+        fn uniform(model: &Model, namespace: &Option<String>) -> bool {
+            match model {
+                Model::Element(q, _) => &q.namespace == namespace,
+                Model::Sequence(parts) => parts.iter().all(|p| uniform(p, namespace)),
+                Model::Repeat(part, _, _) if matches!(part.as_ref(), Model::Element(..)) => {
+                    uniform(part, namespace)
+                }
+                _ => false,
+            }
+        }
+        self.named.get(name).map(|model| {
+            !self.unsupported_attribute_types.contains(name) && uniform(model, namespace)
+        })
+    }
+
     pub fn parse(xml: &str) -> Result<Self, SchemaError> {
         let mut reader = Reader::from_str(xml);
         let root = loop {
@@ -273,13 +283,38 @@ impl Document {
             groups: BTreeMap::new(),
             named: BTreeMap::new(),
             anonymous: Vec::new(),
+            unsupported_attribute_types: BTreeSet::new(),
         };
-        fn collect(node: &Node, document: &mut Document, qualified: bool) {
+        fn qualified_attributes(node: &Node, default_qualified: bool) -> bool {
+            matches!(node.tag.as_str(), "attributeGroup" | "anyAttribute")
+                || (node.tag == "attribute"
+                    && (node.attr("ref").is_some()
+                        || match node.attr("form") {
+                            Some("qualified") => true,
+                            Some("unqualified") => false,
+                            _ => default_qualified,
+                        }))
+                || node
+                    .children
+                    .iter()
+                    .any(|child| qualified_attributes(child, default_qualified))
+        }
+        fn collect(
+            node: &Node,
+            document: &mut Document,
+            qualified: bool,
+            attributes_qualified: bool,
+        ) {
             let ns = document.namespace.as_deref();
             if node.tag == "complexType" {
                 let model = content(node, ns, qualified);
                 if let Some(name) = node.attr("name") {
                     document.named.insert(QName::new(ns, name), model);
+                    if qualified_attributes(node, attributes_qualified) {
+                        document
+                            .unsupported_attribute_types
+                            .insert(QName::new(ns, name));
+                    }
                 } else {
                     document.anonymous.push((
                         format!("anonymous complexType at byte {}", node.position),
@@ -288,7 +323,7 @@ impl Document {
                 }
             }
             for child in &node.children {
-                collect(child, document, qualified);
+                collect(child, document, qualified, attributes_qualified);
             }
         }
         for child in &root.children {
@@ -301,7 +336,12 @@ impl Document {
                 }
             }
         }
-        collect(&root, &mut document, qualified);
+        collect(
+            &root,
+            &mut document,
+            qualified,
+            root.attr("attributeFormDefault") == Some("qualified"),
+        );
         Ok(document)
     }
     pub fn adopt_namespace(&mut self, namespace: &str) {
@@ -344,6 +384,13 @@ impl Document {
                 _ => {}
             }
         }
+        self.unsupported_attribute_types = std::mem::take(&mut self.unsupported_attribute_types)
+            .into_iter()
+            .map(|mut q| {
+                name(&mut q, namespace);
+                q
+            })
+            .collect();
         for collection in [&mut self.groups, &mut self.named] {
             *collection = std::mem::take(collection)
                 .into_iter()

crates/polyxml-core/tests/test_rust_codegen.rs

@@ -1505,3 +1505,52 @@ assert_eq!(parsed,value);let object:serde_json::Value=serde_json::from_str(&json
         );
     }
 }
+
+#[test]
+fn incremental_root_writer_is_schema_scoped() {
+    let xsd = include_str!("../../../tests/fixtures/incremental/items.xsd");
+    for zero_copy in [true, false] {
+        let ir = XsdParser::new().parse_str(xsd).unwrap();
+        let code = RustCodegen::new(RustOptions {
+            zero_copy,
+            ..Default::default()
+        })
+        .generate_module(&ir);
+        assert!(code.contains("pub fn write_batch_items"));
+        assert!(code.contains("for item in items"));
+        assert!(code.contains("start.push_attribute((\"xmlns\", \"urn:items\"))"));
+        assert!(code.contains("if count < 1"));
+        assert!(code.contains("item.encode_xml(writer, Some(\"Item\"))"));
+        let bounded = xsd.replace("maxOccurs=\"unbounded\"", "maxOccurs=\"2\"");
+        let ir = XsdParser::new().parse_str(&bounded).unwrap();
+        let code = RustCodegen::new(RustOptions::default()).generate_module(&ir);
+        assert!(code.contains("if count == 2"));
+        for unsupported in [
+            xsd.replace(
+                "elementFormDefault=\"qualified\"",
+                "elementFormDefault=\"qualified\" attributeFormDefault=\"qualified\"",
+            ),
+            xsd.replace("<xs:sequence>", "<xs:sequence minOccurs=\"0\">"),
+            xsd.replace(
+                "name=\"Item\" type=\"t:ItemType\"",
+                "name=\"Item\" type=\"t:ItemType\" nillable=\"true\"",
+            ),
+            xsd.replace(
+                "elementFormDefault=\"qualified\"",
+                "elementFormDefault=\"unqualified\"",
+            ),
+            xsd.replace(
+                "name=\"Batch\" type=\"t:BatchType\"",
+                "name=\"Batch\" type=\"t:BatchType\" nillable=\"true\"",
+            ),
+        ] {
+            let ir = XsdParser::new().parse_str(&unsupported).unwrap();
+            let code = RustCodegen::new(RustOptions::default()).generate_module(&ir);
+            assert!(
+                !code.contains("pub fn write_batch_items"),
+                "{unsupported}\n{:?}",
+                ir.upa_documents
+            );
+        }
+    }
+}