refactor(events): seal ServerAck with non_exhaustive + bon builder

AGENTS.md

@@ -31,7 +31,7 @@ cargo test -p e2e-tests          # requires mock server running
 - **Protocol**: Cross-reference **whatsmeow**, **Baileys**, and captured WhatsApp Web JS (`docs/captured-js/`) to verify implementations.
 - **IQ Requests**: Use `client.execute(Spec::new(&jid)).await?` pattern. IqSpec constructors take `&Jid` not `Jid`.
 - **New features**: Expose via `src/features/mod.rs`, re-export in `src/lib.rs`.
-- **Event payloads**: Model a maybe-absent field as `Option<T>`, never an empty-string/zero sentinel. Pre-1.0 the payload structs stay constructible (not `#[non_exhaustive]`), so consumers read the fields they need instead of destructuring exhaustively; see the `Event` doc in `wacore/src/types/events.rs` for the full stability policy.
+- **Event payloads**: Seal each payload struct with `#[non_exhaustive]` + `#[derive(bon::Builder)]` so fields can be added without breaking consumers; construct via the generated builder (`Type::builder()…build()`), not a struct literal. Model a maybe-absent field as `Option<T>` (gets a `maybe_*` setter), never an empty-string/zero sentinel. The seal is rolling out per struct, so not every payload carries the attribute yet; see the `Event` doc in `wacore/src/types/events.rs` for the full stability policy.
 - **Wire-tagged enums**: Every protocol enum uses `#[derive(WireEnum)]`. The `#[wire = "..."]` (or `#[wire = NUM]` for int mode) attribute is the SINGLE source of truth for each variant's wire value. Do NOT also derive `serde::Serialize`/`Deserialize` or add `#[serde(rename_all)]` — the derive owns both. Three modes: unit-string (default), tagged-with-payload (`#[wire(tag = "type")]` on the enum, optional `#[wire_alias = "..."]` and `#[wire(skip)]` on fields, `#[wire_fallback]` for catch-all), and int (`#[wire(kind = "int")]`). In tagged mode the derive auto-generates a sibling `<Name>Tag` enum; parsers must dispatch via `<Name>Tag::try_from(node.tag.as_ref())` instead of matching string literals, so renaming a wire tag stays a single-attribute change.
 
 ## Detailed Docs

Cargo.toml

@@ -63,6 +63,7 @@ buffa-build = { version = "0.8.1", default-features = false }
 buffa-descriptor = { version = "0.8.1", default-features = false }
 bytemuck = { version = "1.25", default-features = false }
 bytes = { version = "1.12", default-features = false }
+bon = { version = "3.9.3", default-features = false, features = ["std"] }
 cbc = { version = "0.2", features = ["alloc"] }
 chrono = { version = "0.4", default-features = false }
 compact_str = { version = "0.9", default-features = false }

src/client/node_io.rs

@@ -1147,16 +1147,17 @@ impl Client {
             .has_handler_for(wacore::types::events::EventKind::ServerAck)
             && let Some(id) = &ack_id
         {
-            let ack = wacore::types::events::ServerAck {
-                id: id.as_str().to_string(),
-                class: node.get_attr("class").map(|v| v.as_str().to_string()),
-                from: node.get_attr("from").and_then(|v| v.as_str().parse().ok()),
-                timestamp: node
-                    .get_attr("t")
-                    .and_then(|v| v.as_str().parse::<i64>().ok())
-                    .and_then(|secs| chrono::DateTime::from_timestamp(secs, 0)),
-                error: ack_error.as_ref().map(|v| v.as_str().to_string()),
-            };
+            let ack = wacore::types::events::ServerAck::builder()
+                .id(id.as_str().to_string())
+                .maybe_class(node.get_attr("class").map(|v| v.as_str().to_string()))
+                .maybe_from(node.get_attr("from").and_then(|v| v.as_str().parse().ok()))
+                .maybe_timestamp(
+                    node.get_attr("t")
+                        .and_then(|v| v.as_str().parse::<i64>().ok())
+                        .and_then(|secs| chrono::DateTime::from_timestamp(secs, 0)),
+                )
+                .maybe_error(ack_error.as_ref().map(|v| v.as_str().to_string()))
+                .build();
             self.core
                 .event_bus
                 .dispatch(wacore::types::events::Event::ServerAck(ack));

wacore/Cargo.toml

@@ -48,6 +48,7 @@ async-channel = { workspace = true }
 async-lock = { workspace = true }
 async-trait = { workspace = true }
 base64 = { workspace = true }
+bon = { workspace = true }
 buffa = { workspace = true }
 bytes = { workspace = true }
 chrono = { workspace = true, features = ["now", "serde"] }

wacore/src/types/events.rs

@@ -605,15 +605,17 @@ pub struct DisappearingModeChanged {
 
 /// An event dispatched by the client to registered handlers.
 ///
-/// # Stability (pre-1.0)
+/// # Stability
 ///
 /// The enum is `#[non_exhaustive]`, so match arms must keep a `_` catch-all.
-/// The payload structs are *not* sealed: while the crate is `0.x`, an existing
-/// payload may gain new fields in a minor release, so read the fields you need
-/// (`ack.class`) or keep a `..` rest when destructuring, rather than binding
-/// every field. A maybe-absent field is always modeled as `Option<T>`, never
-/// an empty-string / zero sentinel. Sealing the payloads behind
-/// `#[non_exhaustive]` + constructors is deferred to the 1.0 API freeze.
+/// Payload structs are being sealed the same way — `#[non_exhaustive]` plus a
+/// `bon` builder for construction — so a payload can gain fields without
+/// breaking consumers. Read the fields you need (`ack.class`) or keep a `..`
+/// rest when destructuring, rather than binding every field. Construct payloads
+/// via their generated builder (`ServerAck::builder()…build()`), not a struct
+/// literal; a maybe-absent field is always modeled as `Option<T>` (with a
+/// `maybe_*` setter), never an empty-string / zero sentinel. The seal is
+/// rolling out per struct, so not every payload carries the attribute yet.
 #[derive(Debug, Clone, Serialize)]
 #[non_exhaustive]
 pub enum Event {
@@ -1201,7 +1203,8 @@ pub struct Receipt {
 /// outgoing stanza. Server acks cover every outgoing stanza class — message,
 /// receipt, notification, call — so consumers should filter on [`class`](Self::class)
 /// before correlating ids.
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, bon::Builder)]
+#[non_exhaustive]
 pub struct ServerAck {
     /// Id of the acked stanza (for a sent message, its message id).
     pub id: String,