OverflowPolicy

@open-agent-loops/core

type OverflowPolicy<T> = 
  | "drop-oldest"
  | "drop-newest"
  | "block"
  | {
  coalesce: (buffered, incoming) => T[];
};

Defined in: primitives/bounded-buffer.ts:85

What happens to an item pushed into a BoundedBuffer that is already at capacity. The four cases are genuinely distinct — they differ on whether the arrival is kept and whether the producer is asked to slow down:

• "drop-oldest" — evict the head to make room, admit the arrival. Stale context is the cheapest thing to lose; good for live ingress.
• "drop-newest" — refuse the arrival, leave the buffer untouched. The arrival is discarded.
• "block" — refuse the arrival but report it as blocked, not dropped: the caller still owns it and should apply backpressure upstream (stop producing / await space). This is the only policy that propagates pressure to the producer, so it is for blockable producers only.
• { coalesce } — fold the arrival into the buffered items via merge instead of dropping. merge receives a snapshot of the buffered items and the incoming item and returns the new buffer contents; it must not grow the buffer past capacity (that is the whole point — it absorbs the arrival without growing).

A user-visible "I'm catching up" reply is not a separate policy: any push that does not fully admit its items is observable via PushResult, so the caller reacts to that.

Type Parameters