feat(ir): carry argument paths, element values, cardinality and union depth across mixins

README.md

@@ -50,7 +50,17 @@ Note the contract version: this raised `schemaVersion` to **2.0.0**, and it is a
 
 Additive in 3.0.0, so a 2.x consumer can ignore them: `unknownValue` on enum-accessor fields; `syntheticName` / `bitPosition` in the enum catalog; and the catalog itself growing from 328 to 403 entries so every `enumRef` resolves against it — 75 of the 87 referenced `(module, name)` pairs were in no catalog before.
 
-Anything the extractor sees but cannot resolve structurally is counted under `manifest.diagnostics.iq.dropsByReason` rather than omitted, so "no constraint here" and "a constraint we failed to extract" never look alike. `manifest.diagnostics.iq.constraints`, `diagnostics.iq.targets.resolved` and `diagnostics.notif.actions` are floor-guarded: a WA refactor that hides one of these constructs fails the update instead of silently emptying a field. The unresolved states are guarded the other way — `scripts/lint-ir.py` pins the count of unaddressed requests and of unjudged accessors to an exact baseline. A rise means a constraint is being lost; a fall means extraction improved and the baseline owes an update. Either way the lint fails, so neither direction passes unnoticed.
+### Enough to *call* WhatsApp's own builder, not only to encode the stanza yourself
+
+Everything above describes the wire. That serves a client that encodes the stanza itself — it needs to know a group create carries a `<participant jid=…>` of type `user_jid`. It does not serve a client that **runs WhatsApp's own modules**, which needs the other half: that the value goes in `args.participantArgs[].participantJid`. Neither half implies the other — WA picks the argument key independently of the attribute it lands in (`subjectElementValue` becomes the *text* of `<subject>`) — and almost every request is composed out of mixins, so the argument key is usually defined in a different module from the tag it fills. So the request side also carries the builder:
+
+- **Argument paths** (`argPath` on a request node, an attribute, or an element content) — the absolute path from the builder's argument object, as segments. `list` marks the one segment that is indexed, and only that one: `REPEATED_CHILD(template, list, min, max)` calls the template once per element, while `OPTIONAL_CHILD`/`HAS_OPTIONAL_CHILD` hand the object over whole. The same suffix in the wrong place writes the value where the vendor builder never reads it, and the stanza goes out without it. Recovered structurally — from the function's single argument parameter and the `var x = <param>.<key>` destructure — never from a name: `…Args`, `has…` and `any…` are WA conventions that make the IR readable, not evidence. A path that isn't structurally recoverable is absent and counted under `manifest.diagnostics.iq.builder`, never guessed. The legacy `WAWeb*Job` builders take positional parameters rather than one options object, so they get no path at all and are counted as such.
+- **Cardinality of a request child** (`presence`, plus `repeatMin`/`repeatMax`) — the three states `WASmaxChildren` distinguishes, of which the wire shows one. `<locked/>` on a group create is a *presence marker*: its template takes no arguments, its whole meaning is being there, and a consumer can model it as a `bool` — which it must not do for an optional child and cannot do for an empty required one, all three of which are the same empty element on the wire. The repeat bounds are the ones a server enforces (`add/participant` 1..1024, `query/group` 1..10000, `media_list` 0..10); a `repeatMin` with no `repeatMax` is WA's explicit `1/0`, i.e. unbounded above, which stays distinguishable from a child that states no bound at all and has neither.
+- **Element values that survive the mixin boundary** (`content`) — `smax("subject", null, subjectElementValue)` is the entire payload of a group rename. WA's builders bind that payload to a local before writing it, and a bare local used to be ignored outright in case it was a node variable. It is now told apart structurally: a local that resolves to an argument path is content, one that resolves to a `smax(…)` call is a child.
+
+Note the contract version: this is additive on top of 3.0.0 and raises `schemaVersion` to **3.1.0**, with the minor checked rather than assumed. Every new property is optional and skipped at its default, no existing field's value space widened, and each committed `*/index.json` validates clean against its own **3.0.0** schema (0 errors across all 12 domains) — so a 3.0 consumer reads the new documents unchanged and needs no migration. One field changed *value* rather than shape: `content` is now populated on 45 request nodes that previously carried none, an optional field filled in where the builder does supply a payload. A consumer that treated "no `content`" as "this request has no body" was already wrong about those requests; it is now told so.
+
+Anything the extractor sees but cannot resolve structurally is counted under `manifest.diagnostics.iq.dropsByReason` rather than omitted, so "no constraint here" and "a constraint we failed to extract" never look alike. `manifest.diagnostics.iq.constraints`, `diagnostics.iq.targets.resolved`, `diagnostics.iq.builder` and `diagnostics.notif.actions` are floor-guarded: a WA refactor that hides one of these constructs fails the update instead of silently emptying a field. The unresolved states are guarded the other way — `scripts/lint-ir.py` pins the count of unaddressed requests and of unjudged accessors to an exact baseline. A rise means a constraint is being lost; a fall means extraction improved and the baseline owes an update. Either way the lint fails, so neither direction passes unnoticed.
 
 ## Quick start
 

crates/wa-codegen/src/emit.rs

@@ -2465,6 +2465,7 @@ mod tests {
             value: value.map(|v| v.into()),
             required: false,
             enum_ref: None,
+            arg_path: None,
         }
     }
     fn leaf(tag: &str) -> WapChildNode {
@@ -2475,6 +2476,7 @@ mod tests {
             content: None,
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         }
     }
 
@@ -2563,6 +2565,7 @@ mod tests {
             content: None,
             repeats: true,
             variant_groups: vec![],
+            ..Default::default()
         };
         let node = WapChildNode {
             tag: "config".into(),
@@ -2577,6 +2580,7 @@ mod tests {
                     children: vec![item],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -2887,6 +2891,7 @@ mod tests {
                 content: None,
                 repeats: false,
                 variant_groups: groups,
+                ..Default::default()
             };
             let (mut enums, mut fields) = (Vec::new(), Vec::new());
             let reserved = std::collections::HashSet::new();
@@ -3005,6 +3010,7 @@ mod tests {
             content: None,
             repeats: true,
             variant_groups: vec![],
+            ..Default::default()
         };
         let node = WapChildNode {
             tag: "config".into(),
@@ -3019,6 +3025,7 @@ mod tests {
                     children: vec![kid("type"), kid("2fa")],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3056,6 +3063,7 @@ mod tests {
                     children: vec![kid("type")],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3089,6 +3097,7 @@ mod tests {
                     children: vec![kid("my-tag")],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3121,6 +3130,7 @@ mod tests {
             content: None,
             repeats: true,
             variant_groups: vec![],
+            ..Default::default()
         };
         let node = WapChildNode {
             tag: "config".into(),
@@ -3135,6 +3145,7 @@ mod tests {
                     children: vec![kid("foo-bar"), kid("foo_bar")],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3173,6 +3184,7 @@ mod tests {
                     children: vec![kid("item")],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let mut ctx = VariantCtx {
@@ -3205,6 +3217,7 @@ mod tests {
             content: None,
             repeats: true,
             variant_groups: vec![],
+            ..Default::default()
         };
         let node = WapChildNode {
             tag: "config".into(),
@@ -3219,6 +3232,7 @@ mod tests {
                     children: vec![item],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3265,6 +3279,7 @@ mod tests {
                     children: vec![nested],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3310,6 +3325,7 @@ mod tests {
                     children: vec![nested],
                 }],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3486,6 +3502,7 @@ mod tests {
                     ],
                 },
             ],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3567,6 +3584,7 @@ mod tests {
                 optional: false,
                 variants: vec![mk("appid"), mk("voip"), mk("endpoint")],
             }],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3788,6 +3806,7 @@ mod tests {
             content: None,
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (lines, var, _) = build1(&child);
         let code = lines.join("\n");
@@ -3820,6 +3839,7 @@ mod tests {
             content: None,
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (lines, _, _) = build1(&parent);
         let code = lines.join("\n");
@@ -3850,6 +3870,7 @@ mod tests {
             }),
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (lines, _, _) = build1(&node);
         let code = lines.join("\n");
@@ -3878,6 +3899,7 @@ mod tests {
             }),
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3953,6 +3975,7 @@ mod tests {
             }),
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();
@@ -3984,6 +4007,7 @@ mod tests {
             }),
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let (mut enums, mut fields) = (Vec::new(), Vec::new());
         let reserved = std::collections::HashSet::new();

crates/wa-codegen/src/lib.rs

@@ -252,6 +252,7 @@ mod tests {
             value: None,
             required: true,
             enum_ref: None,
+            arg_path: None,
         }
     }
 
@@ -736,6 +737,7 @@ mod tests {
                         content: None,
                         repeats: false,
                         variant_groups: vec![],
+                        ..Default::default()
                     }],
                 },
                 response: ParsedResponse {

crates/wa-codegen/src/spec.rs

@@ -1143,11 +1143,13 @@ mod tests {
                 value: None,
                 required: true,
                 enum_ref: None,
+                arg_path: None,
             }],
             children: vec![],
             content: None,
             repeats: false,
             variant_groups: vec![],
+            ..Default::default()
         };
         let children = vec![
             node("participant", WapAttrKind::UserJid),

crates/wa-codegen/src/stanza_export.rs

@@ -282,6 +282,7 @@ mod tests {
                 module: module.into(),
                 variants: vars,
             }),
+            arg_path: None,
         }
     }
 
@@ -292,6 +293,7 @@ mod tests {
             value: None,
             required: true,
             enum_ref: None,
+            arg_path: None,
         }
     }