An append reports how much of it was new
Every drop the buffer makes is silent, and the total message count looks identical across two identical passes. The delta is the only evidence a caller has that a turn actually landed.
The rule
- A conversation-buffer append reports how many of the incoming messages were added as new entries, and whether that number is greater than zero, alongside the resulting buffer count.
- The number counts appends and not the change in buffer size, because a windowed buffer can evict as many older messages as the call added.
- A deduplicated message and a placeholder replacement each count as zero, since neither adds an entry.
- An append under a refused identity scope reports zero, together with its empty buffer.
What it means
The count that changes is not the buffer's size. A windowed buffer can evict as many older entries as an append adds, so the total count after a call that genuinely added a message can be exactly what it was before. The number a caller needs is how many of the incoming messages actually became new entries — the delta the buffer's own size cannot show. A message dropped as a duplicate, and a placeholder a real result replaces in place, both add zero entries, so both report zero even though the buffer's size does not tell them apart from a message that landed cleanly.
Example
A three-message window already holds three entries; the incoming message is new content, and the window evicts the oldest to make room.
{"count": 3, "appended": 1, "appended_any": true}The buffer is still three messages long — the same size it was — but one of
those three is the message that just arrived, and appended says so where
the count alone could not.
{"count": 2, "appended": 0, "appended_any": false}Here the buffer size does not change either, but for the opposite reason: nothing new landed at all.