Deserializer tests to trigger both bugs:

    it('does not throw when checkKeys=true and a DBRef has a $-prefixed extra field', () => {
      // Old serializeDBRef always used checkKeys=false internally.
      // The new iterative serializer applies the ambient checkKeys to DBRef fields,
      // causing this to throw BSONError when it should not.
      const dbref = new BSON.DBRef('col', new BSON.ObjectId(), undefined, { $custom: 1 });
      expect(() => BSON.serialize({ ref: dbref }, { checkKeys: true })).not.to.throw();
    });

    it('omits undefined DBRef extra fields even when ignoreUndefined=false', () => {
      // Old serializeDBRef hardcoded ignoreUndefined=true for its inner serialization.
      // New code uses the ambient value, so undefined fields become BSON null when
      // the caller sets ignoreUndefined=false.
      const dbref = new BSON.DBRef('col', new BSON.ObjectId(), undefined, { extra: undefined });
      const bytes = BSON.serialize({ ref: dbref }, { ignoreUndefined: false });
      const result = BSON.deserialize(bytes) as { ref: BSON.DBRef };
      expect(result.ref.fields).not.to.have.property('extra');
    });

Use Case

As a... (who is this for)
I want... (what is the desired change)
So that... (why is the change desired)

User Experience

• What is the desired/expected outcome for the user once this ticket is implemented?
• If bug: What is the number of impacted customers? How severe is the impact? Is anyone blocked or broken?

Dependencies

• upstream and/or downstream requirements and timelines to bear in mind

Risks/Unknowns

• What could go wrong while implementing this change? (e.g., performance, inadvertent behavioral changes in adjacent functionality, existing tech debt, etc)
• Is there an opportunity for better cross-driver alignment or testing in this area?
• Is there an opportunity to improve existing documentation on this subject?

Acceptance Criteria

Implementation Requirements

• functional reqs, potential snafus to avoid, performance targets, etc

Testing Requirements

• unit test, spec test sync, etc

Documentation Requirements

• DOCSP ticket, API docs, etc

Follow Up Requirements

• additional tickets to file, required releases, etc
• if node behavior differs/will differ from other drivers, confirm with dbx devs what standard to aim for and what plan, if any, exists to reconcile the diverging behavior moving forward