docs: document reassign-to-persist contract on AggregateFunction.update

State is persisted only for groups whose dict entry was *assigned* during
update() (plus groups carried from a prior batch). An in-place mutation of a
group first seen in the current batch is silently dropped, so finalize() sees
only initial_state() — every result NULL for single-group/single-batch
aggregates. Spell out the immutable-reassign idiom with do/don't examples.

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

Author: rustyconover

vgi/aggregate_function.py

@@ -337,6 +337,22 @@ def update(
         The ``states`` dict is pre-populated with ``initial_state()`` for
         all new group_ids. ``group_ids`` is parallel to each column array.
 
+        IMPORTANT — reassign to persist. Treat state as immutable: to record
+        a change you MUST write it back with ``states[gid] = new_state``. The
+        framework only persists a group whose entry you *assigned* during this
+        call (plus groups already saved from an earlier batch). Mutating the
+        existing object in place — e.g. ``states[gid].items.append(x)`` — is
+        NOT detected for a group first seen in this batch, so its data is
+        silently dropped and ``finalize()`` sees only ``initial_state()``. This
+        bites single-group / single-batch aggregates hardest. Do::
+
+            s = states[gid]
+            states[gid] = MyState(items=s.items + new_items)  # reassign
+
+        not::
+
+            states[gid].items.extend(new_items)  # in-place: may be lost
+
         """
         ...