docs: document if (var x = expr) and m[k].field op= rhs in README and SPEC

Signed-off-by: Cong Wang <cwang@multikernel.io>

Author: congwang-mk

README.md

@@ -62,6 +62,8 @@ KernelScript addresses these problems through revolutionary language features:
 
 ✅ **Zero-boilerplate shared state** - Maps are automatically accessible across all programs as regular global variables in a programming language
 
+✅ **Ergonomic map idioms** - Declaration-as-condition (`if (var s = m[k]) { s.field = ... }`) and compound assignment on map indices (`m[k].count += 1`) compile down to a single presence-checked lookup with in-place mutation, no manual write-back
+
 ✅ **Builtin kfunc support** - Define full-privilege kernel functions that eBPF programs can call directly, automatically generating kernel modules and BTF registrations
 
 ✅ **Unified error handling** - C-style integer throw/catch works seamlessly in both eBPF and userspace contexts, unlike complex Result types
@@ -223,6 +225,27 @@ fn lookup_or_create(ip: IpAddress) -> Counter {
         return 1
     }
 }
+
+// Declaration-as-condition: bind only inside the truthy branch.
+// For struct-valued maps, the bound name is the lookup pointer, so
+// field access auto-derefs and the generated eBPF performs in-place
+// mutation against the underlying entry — no write-back needed.
+pin var ip_stats : hash<IpAddress, PacketInfo>(1024)
+
+@helper
+fn record_packet(ip: IpAddress, size: PacketSize) {
+    if (var stats = ip_stats[ip]) {
+        stats.size = size
+    } else {
+        ip_stats[ip] = PacketInfo { src_ip: ip, dst_ip: 0, protocol: 0, size: size }
+    }
+}
+
+// Compound assignment indexes into struct-valued maps directly:
+@helper
+fn bump_size(ip: IpAddress, delta: PacketSize) {
+    ip_stats[ip].size += delta   // emits a presence-checked ptr->size += delta
+}
 ```
 
 ### Multi-Program Coordination

SPEC.md

@@ -2769,12 +2769,10 @@ var flow_stats : hash<u32, FlowStats>(1024)
 
 @helper
 fn update_flow_stats(flow_id: u32, packet_size: u32) {
-    var stats = flow_stats[flow_id]
-    if (stats != null) {
-        stats.packet_count += 1
-        stats.total_bytes += packet_size
-        stats.avg_packet_size = stats.total_bytes / stats.packet_count
-    }
+    // Compound assignment on a struct-field of a map value emits a single
+    // presence-checked map lookup and mutates in place; see §6.2.5.
+    flow_stats[flow_id].packet_count += 1
+    flow_stats[flow_id].total_bytes  += packet_size
 }
 ```
 
@@ -2825,7 +2823,73 @@ fn main() -> i32 {
 }
 ```
 
-#### 6.2.5 Performance and Code Generation
+#### 6.2.5 Compound Assignment with Map Indexing
+
+KernelScript extends compound assignment to map index expressions, so a
+counter update against a map value can be written without an intermediate
+variable or an explicit write-back.
+
+##### 6.2.5.1 Scalar map values
+
+When the map's value type is an integer, `m[k] op= rhs` reads the current
+entry, applies `op`, and writes the result back. If the entry is absent
+the read yields zero, so the operation creates the entry on first use.
+
+```kernelscript
+var packet_counts : hash<u32, u64>(1024)
+
+@xdp
+fn rate_limiter(ctx: *xdp_md) -> xdp_action {
+    var src_ip = extract_src_ip(ctx)
+    packet_counts[src_ip] += 1   // read-modify-write; creates entry if absent
+    return XDP_PASS
+}
+```
+
+The supported operators are `+=`, `-=`, `*=`, `/=`, `%=`. The map's value
+type must be one of the integer primitives.
+
+##### 6.2.5.2 Struct-field map values
+
+When the map's value type is a struct, `m[k].field op= rhs` mutates a
+single field of an existing entry in place. The compiler lowers the form
+to a presence-checked pointer mutation:
+
+```kernelscript
+struct PacketStats {
+    count: u64,
+    total_bytes: u64,
+}
+
+var ip_stats : hash<u32, PacketStats>(1024)
+
+@xdp
+fn observe(ctx: *xdp_md) -> xdp_action {
+    var ip = extract_src_ip(ctx)
+    var len = packet_len(ctx)
+    ip_stats[ip].count       += 1
+    ip_stats[ip].total_bytes += len
+    return XDP_PASS
+}
+```
+
+Semantics:
+
+- **Map identifier required.** The left-hand side must be `IDENT[expr].field op= rhs`;
+  arbitrary LHS expressions are not allowed.
+- **Value type must be a struct.** `field` is resolved against the map's value
+  struct definition; an unknown field is a compile-time error.
+- **Field type drives `op`.** The named field must be one of the integer
+  primitives; the right-hand side must be assignment-compatible with the field type.
+- **Presence check, no creation.** If the entry is absent the statement is a
+  no-op — unlike scalar `m[k] op= rhs`, the struct-field form does *not*
+  create a default entry. To handle the missing case, pair it with an
+  explicit `else` using the declaration-as-condition form (see §7.5.1).
+- **Single map lookup.** Generated code performs one `bpf_map_lookup_elem`,
+  guards on the returned pointer, and writes through it
+  (`if (p) { p->field = p->field op rhs; }`); there is no separate write-back.
+
+#### 6.2.6 Performance and Code Generation
 
 Compound assignments generate efficient code in both contexts:
 
@@ -3220,6 +3284,13 @@ fn main(args: Args) -> i32 {
 ### 7.5 Control Flow Statements
 
 #### 7.5.1 Conditional Statements
+
+KernelScript provides two `if` forms: a standard expression-condition
+form and a *declaration-as-condition* form that combines a single-use
+binding with a presence check.
+
+##### 7.5.1.1 Expression-condition form
+
 ```kernelscript
 // Conditional statements
 if (condition) {
@@ -3231,6 +3302,48 @@ if (condition) {
 }
 ```
 
+##### 7.5.1.2 Declaration-as-condition form (`if (var name = expr)`)
+
+```kernelscript
+if (var name = expr) {
+    // then-branch: `name` is in scope and bound to `expr`'s value
+} else {
+    // else-branch: `name` is *not* in scope
+}
+```
+
+The branch is taken iff `expr` produces a *present* value:
+
+- **Map index** (`m[k]`): present iff the entry exists. The bound name is
+  the lookup pointer, so field access auto-derefs and field assignments
+  mutate the underlying map entry in place — no explicit write-back is
+  needed:
+
+  ```kernelscript
+  if (var stats = ip_stats[ip]) {
+      stats.count = stats.count + 1   // writes through the lookup pointer
+  } else {
+      ip_stats[ip] = PacketStats { count: 1, total_bytes: 0 }
+  }
+  ```
+
+- **Pointer-returning expression**: present iff non-null. Useful with
+  helpers and kfuncs that may return `null`.
+
+Semantics:
+
+- **Single evaluation.** `expr` is evaluated exactly once; its presence
+  test guards both branches.
+- **Scoping.** `name` is in scope only inside the then-branch. Referencing
+  it from the else-branch (or after the `if`) is a compile-time error.
+- **No reassignment.** `name` shadows nothing visible to the else-branch
+  and may shadow an outer binding only inside the then-branch.
+- **Else is optional.** As with the expression-condition form, the
+  `else` branch may be omitted.
+- **Lowering.** The form lowers to a single `bpf_map_lookup_elem` (or the
+  underlying pointer-returning call), a null check, and the chosen
+  branch — there is no second lookup.
+
 #### 7.5.2 Match Expressions
 
 KernelScript provides `match` expressions for efficient multi-way branching. Match is an expression that returns a value and can be used anywhere an expression is expected.
@@ -4303,14 +4416,47 @@ statement = expression_statement | assignment_statement | declaration_statement
             try_statement | throw_statement | defer_statement 
 
 expression_statement = expression 
-assignment_statement = identifier assignment_operator expression 
-assignment_operator = "=" | "+=" | "-=" | "*=" | "/=" | "%=" 
+
+assignment_statement   = simple_assignment | compound_assignment | field_assignment |
+                         arrow_assignment  | index_assignment    | compound_index_assignment |
+                         compound_field_index_assignment 
+
+simple_assignment              = identifier "=" expression                              (* x = e *)
+compound_assignment            = identifier compound_operator expression                (* x op= e *)
+field_assignment               = primary_expression "." identifier "=" expression       (* o.field = e *)
+arrow_assignment               = primary_expression "->" identifier "=" expression      (* p->field = e *)
+index_assignment               = expression "[" expression "]" "=" expression           (* m[k] = e *)
+compound_index_assignment      = expression "[" expression "]" compound_operator expression
+                                                                                         (* m[k] op= e:
+                                                                                            scalar map values; reads, applies op, writes back;
+                                                                                            absent entries read as 0, so the form creates an
+                                                                                            entry on first use. See §6.2.5.1. *)
+compound_field_index_assignment = identifier "[" expression "]" "." identifier compound_operator expression
+                                                                                         (* m[k].field op= e:
+                                                                                            struct-valued map; lowers to a single
+                                                                                            bpf_map_lookup_elem + null-checked
+                                                                                            ptr->field op= e; absent entries are a no-op
+                                                                                            (no entry is created). See §6.2.5.2. *)
+
+assignment_operator = "=" | compound_operator
+compound_operator   = "+=" | "-=" | "*=" | "/=" | "%=" 
 
 declaration_statement = "var" identifier [ ":" type_annotation ] "=" expression 
 
-if_statement = "if" "(" expression ")" "{" statement_list "}" 
-               { "else" "if" "(" expression ")" "{" statement_list "}" }
-               [ "else" "{" statement_list "}" ] 
+if_statement = expression_if | iflet_if 
+
+expression_if = "if" "(" expression ")" "{" statement_list "}" 
+                { "else" "if" "(" expression ")" "{" statement_list "}" }
+                [ "else" "{" statement_list "}" ]
+
+iflet_if = "if" "(" "var" identifier "=" expression ")" "{" statement_list "}"
+           [ "else" ( "{" statement_list "}" | iflet_if | expression_if ) ]
+           (* Declaration-as-condition: the right-hand side is evaluated once;
+              the then-branch is taken iff the value is *present* (a map hit
+              or a non-null pointer). `identifier` is bound only inside the
+              then-branch. For map-index right-hand sides the binding is the
+              lookup pointer (field access auto-derefs, field writes mutate
+              the underlying entry in place). See §7.5.1.2. *) 
 
 for_statement = "for" "(" identifier "in" expression ".." expression ")" "{" statement_list "}" |
                 "for" "(" identifier "," identifier ")" "in" expression "{" statement_list "}"