eidCache: make mergeCache take and return cache format

[mosherBT]

Why

The cache and the wire disagree on how refs is keyed, and mergeCache only understood the wire. Handed a cache which is what a wrapper has after setTargeting overwrote its key it found no ext.optable.ref pointer, dropped every ref, and returned an empty staleUid2s. UID2 then never refreshes, with no error.

Related to #333 WIP PR

What Changed

The wire format is unchanged everywhere. Conversion happens at the cache.

• mergeCache takes and returns cache format on both arguments, reading refs[source] instead of following a pointer. A cache read back from storage merges as-is; a wire response goes through replaceCache first.
• replaceCache is idempotent. It wasn't: given a value with no pointers left it resolved against pointers that were gone and returned {}, wiping the refs. That made it unsafe to apply defensively.
• resolveRefs lets the last EID for a source win, matching which EID mergeCache keeps, so a source listed twice cannot end up holding the other EID's refresh material.

Example flow:

Response from targeting1

  { "ortb2": { "user": { "eids": [
       { "source": "uidapi.com",   "uids": [{ "id": "A4AAAAABc…", "atype": 3, "ext": { "optable": { "ref": "0" } } }] },
       { "source": "liveramp.com", "uids": [{ "id": "XY1234…",    "atype": 3 }] } ] } },
    "refs": { "0": { "advertising_token": "A4AAAAABc…", "refresh_token": "AAAAAQ…",
                     "refresh_response_key": "wR5t6H…", "refresh_from": 1758041000000,
                     "refresh_expires": 1758127400000, "identity_expires": 1758124000000 } } }

Stored in local storage this format:

  { "ortb2": { "user": { "eids": [
       { "source": "uidapi.com",   "uids": [{ "id": "A4AAAAABc…", "atype": 3 }] },
       { "source": "liveramp.com", "uids": [{ "id": "XY1234…",    "atype": 3 }] } ] } },
    "refs": { "uidapi.com": { "refresh_token": "AAAAAQ…", "refresh_response_key": "wR5t6H…",
                              "refresh_from": 1758041000000, … } } }

Then on another page load with cache as above and targeting like this:

  { "ortb2": { "user": { "eids": [
       { "source": "uidapi.com",   "uids": [{ "id": "A4AAAAABc…", "atype": 3, "ext": { "optable": { "ref": "0" } } }] },
       { "source": "liveramp.com", "uids": [{ "id": "XY1234…",    "atype": 3 }] } ] } },
    "refs": { "0": { "advertising_token": "A4AAAAABc…", "refresh_token": "AAAAAQ…",
                     "refresh_response_key": "wR5t6H…", "refresh_from": 1758041000000,
                     "refresh_expires": 1758127400000, "identity_expires": 1758124000000 } } }

before we relied on the pointer returning the cache back so end up with this in cache

  { "ortb2": { "user": { "eids": [
       { "source": "uidapi.com",   "uids": [{ "id": "A4BBBBBd…", "atype": 3 }] },
       { "source": "liveramp.com", "uids": [{ "id": "XY9999…",   "atype": 3 }] } ] } },
    "refs": {} }

Now using getRefData we get

  { "ortb2": { "user": { "eids": [
       { "source": "uidapi.com",   "uids": [{ "id": "A4BBBBBd…", "atype": 3 }] },
       { "source": "liveramp.com", "uids": [{ "id": "XY9999…",   "atype": 3 }] } ] } },
    "refs": { "uidapi.com": { "refresh_token": "BBBBCC…", "refresh_from": 1758044000000, … } } }

How to Test

Unit tests cover the cache-read-back round trip that previously lost refs, replaceCache idempotency, and the existing duplicate-source pairing rule.

• Tested
• Docs updated

Notes

• Breaking change
• Requires release