docs(examples,README,SPEC): adopt if (var x = expr) for remaining presence checks

Migrates the `var x = expr; if (x != null) { ... uses x ... }` shape to
the IfLet form wherever the bound name is used inside the truthy branch.

Examples (9 sites):
- `safety_demo.ks`: scalar map count update.
- `ringbuf_demo.ks`: two `network_events.reserve()` /
  `security_events.reserve()` patterns.
- `map_operations_demo.ks`: `shared_stats[batch_key]` in-place mutation
  (drops the redundant write-back) and `event_stream.reserve()`.
- `type_checking.ks`: `connection_stats[header.src_ip]` scalar update.
- `types_demo.ks`: four sites — `packet_filter[info]`, two scalar
  `connection_count` / `protocol_stats` updates, and the
  `extract_packet_info` pointer-returning helper.

README:
- The `lookup_or_create` snippet, which still showed the old shape, now
  uses IfLet directly.

SPEC (8 sites):
- §3.1.2 (TC programs): `connection_tracker` helper.
- §4.6.7 (Map Integration with Pointers): `map_pointer_operations` —
  the canonical example for "map lookup returns pointer" now uses IfLet.
- §5.2 (Global Maps): two `flow_stats` lookups now collapse from a
  presence check + redundant lookup to a single IfLet.
- §9.2 (Top-Level Userspace Coordination): `process_events` ringbuf
  read.
- §10.2 (Transparent Dynptr Integration): two `reserve()`-and-write
  examples — drops the explicit `: *u8` annotation since IfLet's
  grammar doesn't support a binding type annotation; the type is
  inferred from `reserve()`'s return type and noted in a comment.
- §10.4 (Memory Lifetime): `cache_map[key]` lifetime-safety example.
- §10.6 (Cross-Context Memory Safety): two `shared_map[0]` examples.

Sites left intentionally untouched in both `examples/` and SPEC:
- `m[k] != null` with the body using only `m[k] op= rhs` (rate_limiter,
  maps_demo:87, map_operations_demo:60) — IfLet adds an unused binding.
- All `== null` shapes (object_allocation, ringbuf_demo program-load
  checks, test_error_handling) — IfLet branches on presence, not
  absence.
- `tcp_info != null && tcp_info.flags & TCP_SYN` (SPEC §3.1.2 ddos
  example) — compound condition; IfLet doesn't desugar to `&&`.
- `var buffer = kzalloc(...); if (buffer != null) { mark_secure } return buffer`
  (SPEC §3.6.5) — `return buffer` is outside the if; IfLet would put
  the binding out of scope at the return.
- `return cache_entry != null && cache_entry.is_valid` (SPEC
  cache-checksum example) — return-as-expression, not an if.

Pre-existing safety_demo stack-overflow (608 bytes > 512) is unrelated
and predates this PR; verified by stashing the migrations and
re-compiling — same 608-byte error.

84 alcotest suites still green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: congwang-mk

README.md

@@ -215,10 +215,11 @@ fn handle_action(action: FilterAction) -> xdp_action {
     }
 }
 
-// Map lookup and update patterns
+// Map lookup and update patterns — declaration-as-condition binds
+// `count` only inside the truthy branch; one map lookup, no extra
+// presence-check variable.
 fn lookup_or_create(ip: IpAddress) -> Counter {
-    var count = connection_count[ip]
-    if (count != null) {
+    if (var count = connection_count[ip]) {
         return count  // Entry exists
     } else {
         connection_count[ip] = 1  // Create new entry

SPEC.md

@@ -1476,8 +1476,7 @@ fn ddos_protection(ctx: *xdp_md) -> xdp_action {
 
 @tc("ingress")
 fn connection_tracker(ctx: *__sk_buff) -> i32 {
-    var tcp_info = extract_tcp_info(ctx)  // Reuse same helper
-    if (tcp_info != null) {
+    if (var tcp_info = extract_tcp_info(ctx)) {  // Reuse same helper
         track_connection(tcp_info.src_port, tcp_info.dst_port)
     }
     return 0  // TC_ACT_OK
@@ -2357,9 +2356,9 @@ fn ebpf_pointer_usage(ctx: *xdp_md) -> xdp_action {
         }
     }
     
-    // Dynptr-backed pointers (transparent to user)
-    var log_buffer: *u8 = event_log.reserve(256)  // Returns dynptr-backed pointer
-    if (log_buffer != null) {
+    // Dynptr-backed pointers (transparent to user) — `log_buffer` is the
+    // *u8 returned by reserve(), in scope only inside the truthy branch.
+    if (var log_buffer = event_log.reserve(256)) {
         // Regular pointer operations - compiler uses dynptr API internally
         log_buffer[0] = EVENT_TYPE_PACKET
         write_packet_summary(log_buffer + 1, packet_data, 255)
@@ -2428,15 +2427,14 @@ var flow_map : hash<FlowKey, FlowData>(1024)
 
 @helper
 fn map_pointer_operations(flow_key: FlowKey) {
-    // Map lookup returns pointer to value
-    var flow_data = flow_map[flow_key]
-    
-    if (flow_data != null) {
+    // Declaration-as-condition: a single map lookup; `flow_data` is the
+    // returned pointer, in scope only inside the truthy branch.
+    if (var flow_data = flow_map[flow_key]) {
         // Direct modification through pointer
         flow_data->packet_count += 1
         flow_data->byte_count += packet_size
         flow_data->last_seen = bpf_ktime_get_ns()
-        
+
         // Compiler tracks map value lifetime
         // flow_data becomes invalid after certain map operations
     }
@@ -2605,9 +2603,8 @@ fn egress_monitor(ctx: *__sk_buff) -> i32 {
 fn security_analyzer(ctx: LsmContext) -> i32 {
     var flow_key = extract_flow_key_from_socket(ctx)?
     
-    // Check global flow statistics
-    if (global_flows[flow_key] != null) {
-        var flow_stats = global_flows[flow_key]
+    // Check global flow statistics — single lookup via IfLet
+    if (var flow_stats = global_flows[flow_key]) {
         if (flow_stats.is_suspicious()) {
             security_events.submit(SecurityEvent {
                 event_type: EVENT_TYPE_SUSPICIOUS_CONNECTION,
@@ -2617,7 +2614,7 @@ fn security_analyzer(ctx: LsmContext) -> i32 {
             return -EPERM  // Block connection
         }
     }
-    
+
     return 0  // Allow connection
 }
 ```
@@ -3736,9 +3733,8 @@ pin var global_config : array<ConfigKey, ConfigValue>(64)
 fn security_filter(ctx: LsmContext) -> i32 {
     var flow_key = extract_flow_key_from_socket(ctx)
         
-    // Check global flow statistics for threat detection
-    if (global_flows[flow_key] != null) {
-        var flow_stats = global_flows[flow_key]
+    // Check global flow statistics for threat detection — single lookup
+    if (var flow_stats = global_flows[flow_key]) {
         if (flow_stats.is_suspicious()) {
             global_events.submit(EVENT_THREAT_DETECTED { flow_key })
             return -EPERM  // Block connection
@@ -3779,8 +3775,7 @@ fn start_coordinator() -> i32 {
 
 fn process_events(coordinator: *SystemCoordinator) {
     // Process events from all programs
-    var event = coordinator->global_events.read()
-    if (event != null) {
+    if (var event = coordinator->global_events.read()) {
         if (event.event_type == EVENT_PACKET_PROCESSED) {
             print("Processed packet for flow: ", event.flow_key)
         } else if (event.event_type == EVENT_THREAT_DETECTED) {
@@ -3931,17 +3926,17 @@ var event_log : hash<u32, Event>(1024)
 
 @helper
 fn transparent_dynptr_usage(event_data: *u8, data_len: u32) {
-    // User writes simple pointer code
-    var log_entry: *u8 = event_log.reserve(data_len + 16)  // Dynptr-backed pointer
-    if (log_entry != null) {
+    // User writes simple pointer code — IfLet binds the *u8 returned by
+    // reserve() only inside the truthy branch.
+    if (var log_entry = event_log.reserve(data_len + 16)) {
         // Regular pointer operations - compiler uses dynptr API internally
         var header = log_entry as *EventHeader
         header->timestamp = bpf_ktime_get_ns()
         header->data_len = data_len
-        
+
         // Memory copy using pointer arithmetic
         memory_copy(event_data, log_entry + 16, data_len)
-        
+
         event_log.submit(log_entry)  // Compiler ensures proper cleanup
     }
 }
@@ -4028,15 +4023,14 @@ var cache_map : hash<u32, DataCache>(1024)
 
 @helper
 fn map_lifetime_safety(key: u32) {
-    var cache_entry = cache_map[key]
-    if (cache_entry != null) {
+    if (var cache_entry = cache_map[key]) {
         // Compiler tracks that cache_entry is valid here
         cache_entry->access_count += 1
         cache_entry->last_access = bpf_ktime_get_ns()
-        
+
         // Compiler warns/errors if cache_entry used after invalidating operations
         cache_map[other_key] = other_value  // Invalidates cache_entry
-        
+
         // ❌ Compiler error: "Use of potentially invalidated map value pointer"
         // cache_entry->access_count += 1
     }
@@ -4084,27 +4078,25 @@ fn kernel_side_processing(ctx: *xdp_md) -> xdp_action {
     var packet_data = ctx->data()
     
     // Shared memory through maps - safe across contexts
-    var shared_buffer = shared_map[0]
-    if (shared_buffer != null) {
+    if (var shared_buffer = shared_map[0]) {
         shared_buffer->kernel_processed_count += 1
         memory_copy(packet_data, shared_buffer->data, min(packet_len, 64))
     }
-    
+
     return XDP_PASS
 }
 
 // Userspace cannot directly access kernel pointers
 fn userspace_processing() -> i32 {
     // ❌ Cannot access kernel context pointers directly
     // var packet_data = some_kernel_context.data()  // Compilation error
-    
+
     // ✅ Access through shared maps
-    var shared_buffer = shared_map[0]
-    if (shared_buffer != null) {
+    if (var shared_buffer = shared_map[0]) {
         shared_buffer->userspace_processed_count += 1
         process_shared_data(shared_buffer->data)
     }
-    
+
     return 0
 }
 ```

examples/map_operations_demo.ks

@@ -113,10 +113,8 @@ fn stats_updater(ctx: *__sk_buff) -> i32 {
     // Batch operation pattern - will be detected as batch access
     for (i in 0..20) {
         var batch_key = ifindex + i
-        var entry = shared_stats[batch_key]
-        if (entry != null) {
+        if (var entry = shared_stats[batch_key]) {
             entry.packet_count = entry.packet_count + 1
-            shared_stats[batch_key] = entry
         }
     }
 
@@ -129,8 +127,7 @@ fn event_logger(ctx: *trace_event_raw_sys_enter) -> i32 {
     // Ring buffer output - single writer recommended
     try {
         // Reserve space in the ring buffer
-        var reserved = event_stream.reserve()
-        if (reserved != null) {
+        if (var reserved = event_stream.reserve()) {
             // Successfully reserved space - populate event data inline
             reserved->timestamp = 123456  // Fake timestamp
             reserved->event_type = ctx->id  // Use syscall ID from sys_enter context

examples/ringbuf_demo.ks

@@ -51,8 +51,7 @@ fn get_timestamp() -> u64 {
   }
 
   // Try to reserve space in ring buffer
-  var reserved = network_events.reserve()
-  if (reserved != null) {
+  if (var reserved = network_events.reserve()) {
     // Successfully reserved space - populate event data inline
     reserved->timestamp = get_timestamp()
     reserved->event_type = 1  // PACKET_RECEIVED
@@ -77,8 +76,7 @@ fn get_timestamp() -> u64 {
 // Security monitoring program
 @probe("sys_openat")
 fn security_monitor(dfd: i32, filename: *u8, flags: i32, mode: u16) -> i32 {
-  var reserved = security_events.reserve()
-  if (reserved != null) {
+  if (var reserved = security_events.reserve()) {
     // Successfully reserved space - populate security event inline
     reserved->timestamp = get_timestamp()
     reserved->severity = 2  // Medium severity

examples/safety_demo.ks

@@ -109,8 +109,7 @@ fn array_validation_demo(ctx: *xdp_md) -> xdp_action {
 
   // Safe map access
   var key: u32 = 1
-  var count = packet_stats[key]
-  if (count != null) {
+  if (var count = packet_stats[key]) {
     packet_stats[key] = count + 1
   } else {
     packet_stats[key] = 1

examples/type_checking.ks

@@ -66,9 +66,7 @@ fn classify_protocol(proto: u8) -> ProtocolType {
 @helper
 fn update_statistics(header: PacketHeader) {
   // Type checker validates map operations and key/value types
-  var current_count = connection_stats[header.src_ip]
-  
-  if (current_count != null) {
+  if (var current_count = connection_stats[header.src_ip]) {
     // Type checker ensures arithmetic on compatible types
     connection_stats[header.src_ip] = current_count + 1
   } else {

examples/types_demo.ks

@@ -63,8 +63,7 @@ fn extract_packet_info(ctx: *xdp_md) -> *PacketInfo {
 @helper
 fn get_filter_action(info: PacketInfo) -> FilterAction {
   // Look up in the filter map
-  var action = packet_filter[info]
-  if (action != null) {
+  if (var action = packet_filter[info]) {
     return action
   } else {
     return FILTER_ACTION_ALLOW
@@ -85,17 +84,15 @@ fn protocol_from_u8(proto_num: u8) -> Protocol {
 @helper
 fn update_stats(info: PacketInfo) {
   // Update connection count
-  var current_count = connection_count[info.src_ip]
-  if (current_count != null) {
+  if (var current_count = connection_count[info.src_ip]) {
     connection_count[info.src_ip] = current_count + 1
   } else {
     connection_count[info.src_ip] = 1
   }
-  
+
   // Update protocol stats
   var proto = protocol_from_u8(info.protocol)
-  var stats = protocol_stats[proto]
-  if (stats != null) {
+  if (var stats = protocol_stats[proto]) {
     protocol_stats[proto] = stats + 1
   } else {
     protocol_stats[proto] = 1
@@ -105,9 +102,7 @@ fn update_stats(info: PacketInfo) {
 // Program using all the new types
 @xdp fn packet_inspector(ctx: *xdp_md) -> xdp_action {
   // Extract packet information
-  var packet_info = extract_packet_info(ctx)
-  
-  if (packet_info != null) {
+  if (var packet_info = extract_packet_info(ctx)) {
     // Update statistics
     update_stats(*packet_info)