# Pinned event-mongodb document-key coalescing and automatic acknowledgment boundaries > Source-anchored research for Pinned event-mongodb document-key coalescing and automatic acknowledgment boundaries. Run status: COMPLETED. Parent: [Change Data Capture Patterns](https://llms-explorer.com/tree/change-data-capture-patterns/) · 5 facets · 15 facts · page: https://llms-explorer.com/tree/pinned-event-mongodb-document-key-coalescing-and-automatic-acknowledgment-boundaries/ ## Definitions - Scope inference: Ack(nil) in these branches is not evidence that a handler ran or that a business effect committed, and ignored acknowledgment errors do not prove durable acknowledgment. The reviewed fixtures assert selected delivery/count/closure behavior; they do not establish a crash-atomic protocol combining a business effect, marker, and checkpoint. That protocol remains outside this source contract. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce_test.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/coalesce_unit_test.go) ## How it works - When run selects stop or observes the incoming channel closed, it calls drainPending and returns. drainPending calls Ack(nil) on each non-nil pending message and ignores acknowledgment errors. Close signals stop and waits for stopped; this drain does not flush pending messages to the handler, iterate buffered incoming messages, or iterate previously delivered in-flight messages. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - Ordinary output removes the selected entry from pending and marks its key in flight. The ready scan skips in-flight keys until a done signal deletes that marker. Because ready ranges over a map, this implementation does not establish cross-key FIFO delivery; the ordered list serves eviction. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - At source level, TestCoalescer_EvictionSkipsInflightKeys waits for queued inputs to be absorbed before releasing the in-flight key, then errors if its pending "A2" update is not delivered. TestCoalescer_MaxKeysEviction only logs when the newest "d" key is missing; that newest-key check is not a failing assertion. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce_test.go) ## Problems, failure modes and limitations - Capacity eviction runs after nonempty-key input handling while the pending map exceeds c.maxKeys. It scans the ordered list for the oldest key that is not in flight, warns, calls entry.msg.Ack(nil), ignores its error, and removes the entry without sending it to output. If every candidate is in flight, the loop stops even while capacity remains exceeded. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - Scope inference: this coalescer intentionally removes superseded and capacity-evicted pending events through acknowledgment, and shutdown also acknowledges pending entries. Therefore its source-level contract cannot preserve a complete per-event handler history. The adapter recommends current-state use cases such as cache invalidation and materialized view updates. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/coalesce.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) ## Comparisons and alternatives - Metadata coalescing selects in.msg.Metadata()[metaKey] before payload decoding; the raw coalescer stores the message and a superseded count rather than a decoded payload. This avoids decoding messages that are superseded. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/option.go) - When a nonempty key already has a pending entry, handleInput calls old.msg.Ack(nil), discards the acknowledgment error, replaces the entry with the newer message, increments the superseded count, and moves the key to the back of the eviction list. It supersedes the pending entry rather than the already delivered in-flight event. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - For an empty extracted key, handleInput stores the message under "__nokey__" plus the message ID and returns before supersession and capacity checking. It makes the message eligible for ordinary output rather than synchronously invoking the handler. The bypass assumes distinct generated keys: reusing a message ID can overwrite a pending entry under that same synthetic key. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - The pinned API comment for WithCoalesceMaxKeys says an evicted oldest entry is delivered to the handler. The pinned handleInput implementation instead acknowledges and deletes that entry. This is an attributed documentation-versus-implementation conflict; use the implementation to describe the automatic acknowledgment boundary. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/option.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) ## Facts and statements - CoalesceByDocumentKey delegates to WithCoalesceByMetadata with MetadataDocumentKey. The metadata constant is the literal "document_key" and denotes the string representation of the changed document’s _id. The adapter does not construct a namespace-qualified key. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/coalesce.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/context.go) - At source level, TestRawCoalescer_SupersedesByMetadataKey first delivers one message, queues two messages under the same metadata key, waits for inputsHandled to advance before signaling done, then asserts that the next message ID is "3" and its superseded count is at least one. The counter handshake controls absorption before release; these are fixture assertions, not execution results from this research. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce_test.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go) - The empty-key and missing-metadata fixtures assert delivery of their respective messages. TestCoalescer_ShutdownDrainsPending waits for a pending input to be absorbed and fails if Close does not return before its timeout; it does not count acknowledgment callbacks or assert a successful business effect. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce_test.go) - The MongoDB adapter fixture uses a channel transport and a blocked-first-handler handshake with five published same-key messages. Its final assertions require fewer than five handler deliveries, a nonzero coalesced count, and delivered-plus-coalesced at least one. They do not require exact accounting of all five, exactly two deliveries, or the identity of the latest payload; this fixture does not exercise a live MongoDB transport. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/coalesce_unit_test.go) - The WithCoalesceByKey documentation explicitly describes coalescing state as ephemeral across restarts. The shared coalescer constructs pending and in-flight maps inside run. Its in-memory coalescing history supplies no durable restart history by itself. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/option.go) · [also](https://raw.githubusercontent.com/rbaliyan/event/b112463682d44b0e57d8545e3cdf5d51e112e914/coalesce.go)