[rcbevans]

Closes #293 (follow-up with the corrected, red-teamed fix — see the issue for the initial RCA and the discussion of why a driver-side blanket skip is unsound).

Problem

Deserializers generated for xs:sequence content cannot skip unknown child elements. When a start event matches no element of the content model, every generated state machine declines the event (allow_any: false) and the driver raises ErrorKind::UnexpectedEvent. Unknown content is only tolerated at explicit xs:any positions.

Real-world HPXML files hard-fail because of this: the main HPXML producer (OS-HPXML, used by NREL's ResStock) emits legacy v2-style elements (Site/SiteID, Site/Latitude, Site/Longitude) that exist in no HPXML XSD (v2–v5). In a 489-file corpus (OCHRE samples, BEopt examples, ResStock buildings), 33 files fail to parse.

Example input

<HPXML xmlns='http://hpxmlonline.com/2023/09' schemaVersion='4.0'>
  <!-- ... valid required header ... -->
  <Building>
    <BuildingID id='MyBuilding'/>
    <Site>
      <SiteID id='SiteID'/>          <!-- unknown in v4 content model -->
      <Latitude>40.01</Latitude>     <!-- unknown in v4 content model -->
    </Site>
    <ProjectStatus><EventType>audit</EventType></ProjectStatus>
  </Building>
</HPXML>

Before: Unexpected event: Start(BytesStart { name: "Latitude" }) — the first unknown (SiteID) is declined, the second raises. With v3 types the same file fails because Latitude is unknown there too (it lives at Site/GeoLocation/Latitude).

Root cause

The driver (xsd-parser-types/src/quick_xml/deserialize.rs::handle_event) can only skip a subtree when the deserializer chain reports allow_any: true. Generated xs:sequence state machines never report that for unmatched tags, and the driver cannot distinguish "unknown tag" from "known tag violating cardinality/placement" — a naive blanket skip silently accepts maxOccurs violations and drops known-but-misplaced elements (found by red-teaming the naive fix against group_ref_exact_occurs_boundary).

Fix

Content-model knowledge now lives in the generated code:

1. New defaulted trait method Deserializer::is_known_start_tag(helper, &BytesStart) -> bool (default true, so hand-written deserializers stay strict).
2. The renderer emits an override per generated struct/enum listing its content-model tags (namespace-aware, following group refs and content types).
3. The driver skips an unconsumed Start/Empty only when is_known_start_tag returns false — i.e. the tag is genuinely outside the root type's content model. Cardinality/duplicate/order violations of known tags error exactly as before.
4. The sequence next() template captures its entry state and restores it when an event surfaces unconsumed, so optional/advance-past slots stay open after a skip and in-flight child deserializers remain coherent.

Test

• New feature test tests/feature/unknown_element_in_sequence/: minimal schema + 9 XML variants (unknown between/after known children, nested unknown subtrees, unknown Empty, maxOccurs boundary with and without unknowns, missing-required-with-unknown still errors).
• Driver unit tests (8) covering skip state transitions incl. EOF mid-skip.
• 97 regenerated fixture files (pure additions from the new trait method).
• Full workspace: 699 passed / 0 failed; clippy/fmt/doc clean (excluding the pre-existing benchmark crate compile issue, outside default-members).

Impact

HPXML documents from the primary ecosystem writer (OS-HPXML/ResStock) parse successfully; strict enforcement of the content model is preserved for everything the schema actually declares.