# Pinned event-mongodb BSON envelope and payload codec boundary contracts > Source-anchored research for Pinned event-mongodb BSON envelope and payload codec boundary contracts. Run status: COMPLETED. Parent: [Change Data Capture Patterns](https://llms-explorer.com/tree/change-data-capture-patterns/) · 4 facets · 9 facts · page: https://llms-explorer.com/tree/pinned-event-mongodb-bson-envelope-and-payload-codec-boundary-contracts/ ## Structure and components - The payload map fixture encodes a `bson.M` whose key `string` contains `hello`, key `int` contains `int64(99)`, key `nested` contains `bson.M{"a": "b"}`, and key `list` contains `bson.A{"one", "two"}`. After decoding into `bson.M`, its assertions expect `hello`, `int64(99)`, a nested value of type `bson.D` containing key `a` with value `b`, and a `bson.A` list with `one`, `two`. A separate fixture wraps `[]int{1, 2, 3, 4, 5}` in an `Items` field tagged `bson:"items"`, then compares length and elements. These specific assertions do not establish arbitrary-type round trips. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson_test.go) ## Problems, failure modes and limitations - The invalid-byte fixtures supply garbage bytes, empty bytes, a truncated length prefix, and a length prefix exceeding its buffer. The envelope fixture expects an error, a nil message and `errors.Is(err, evtcodec.ErrDecodeFailure)`; the payload fixture expects an error containing `bson decode`. The payload unsupported-value fixture passes `func() {}` and expects an error containing `bson encode`. These observations report assertions in source, without claiming execution. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson_test.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson_test.go) ## Comparisons and alternatives - The envelope round-trip fixture compares ID and source with equality, timestamp with `out.Timestamp().Equal(tt.timestamp)`, retry count with equality, and payload bytes with `bytes.Equal`. For originally empty metadata it checks only zero length; otherwise it compares length and each key/value. These are fixture assertions rather than execution results from this research pass. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson_test.go) ## Facts and statements - The envelope codec declares `bsonEnvelope` with `id` and `source` strings, `payload` as `bson.Raw`, `metadata` as `map[string]string` with `omitempty`, `timestamp` as `time.Time`, and `retry_count` as `int` with `omitempty`. `Encode(msg evtcodec.Message)` populates these fields from the corresponding message accessors before calling `bson.Marshal(env)`. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson.go) - Envelope `Decode(data []byte)` unmarshals into `bsonEnvelope` and returns `message.New` with ID, source, payload, metadata, `message.WithTimestamp(env.Timestamp)`, and `message.WithRetryCount(env.RetryCount)`. Payload `Decode(data []byte, v any)` instead passes the caller-supplied target `v` to `bson.Unmarshal`; payload `Encode(v any)` passes `v` directly to `bson.Marshal`. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson.go) - Envelope marshal and unmarshal errors return `nil` plus `errors.Join(evtcodec.ErrEncodeFailure, err)` or `errors.Join(evtcodec.ErrDecodeFailure, err)`. Payload errors instead use `fmt.Errorf("bson encode: %w", err)` and `fmt.Errorf("bson decode: %w", err)`. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson.go) - Both codecs return `application/bson` from `ContentType()`. The envelope implementation also exposes `Name()` returning `bson` and asserts `evtcodec.Codec` conformance. The payload implementation calls `evtpayload.Register(BSON{})` from `init()` and asserts `evtpayload.Codec` conformance; its registration fixture retrieves `evtpayload.Get("application/bson")` and checks the result has type `BSON`. (medium confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson.go) · [also](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson_test.go) - The envelope round-trip fixture constructs four cases: `evt-123` from `mydb.orders` with `bson.M{"order_id": "abc", "amount": 4200}`, metadata `map[string]string{"operation": "insert", "collection": "orders"}` and retry count `3`; `evt-456` from `mydb.users` with `bson.M{"name": "alice"}`, nil metadata and retries `0`; `evt-789` from `mydb.empty` with `bson.M{}`, metadata `map[string]string{"k": "v"}` and retries `7`; and `evt-oid` from `mydb.things` with `bson.M{"_id": bson.NewObjectID()}`, metadata `map[string]string{"operation": "update"}` and retries `1`. All use `time.Date(2026, 6, 19, 12, 30, 45, 123000000, time.UTC)`. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/codec/bson_test.go) - The payload struct fixture encodes a `sampleDoc` with a generated `bson.ObjectID`, name `widget`, count `42`, active `true`, score `3.14`, tags `[]string{"a", "b", "c"}`, meta `map[string]int{"x": 1, "y": 2}`, and created time `time.Date(2026, 6, 19, 8, 0, 0, 456000000, time.UTC)`. It decodes into `&out` where `out` is `sampleDoc`, compares scalar fields, compares time using `out.Created.Equal(in.Created)`, and checks tags and meta by length and elements. This describes the fixture source, without claiming it ran. (low confidence) — [source](https://raw.githubusercontent.com/rbaliyan/event-mongodb/ca444aedec31e7e959c0932a8f7577c15312f37e/payload/bson_test.go)