The metadata cache's tunables, sourced from configuration: how long a parsed packument stays fresh, how many distinct (source, package) entries the cache holds, and the resident-byte budget it keeps the held entries under before it evicts.

The default cache tunables: a 60-second TTL, 1024 entries, and a 256 MiB resident budget: short enough that a new publish appears promptly, and large enough to hold a normal install's working set of packages while capping the resident memory a handful of heavy packuments could otherwise dominate.

The metadata-cache handle: the three single-flight stores (the full-packument cache, the single-version cache, and the assembled-representation store). Opaque: built with newMetadataCache and reached only through the accessors. Lives in the composition root (one per process), so every request shares the same caches and their connection-collapsing.

Build a metadata cache from its configuration: the full-packument store, the single-version store, and the assembled-representation store, each over the same TTL and size bound.

Which upstream a cached packument was fetched from: the dimension that partitions the cache by source so distinct upstreams never share an entry.

The discriminator is the upstream's base URL: an upstream is addressed at a distinct URL, and the URL names a location, never a credential, so keying on it keeps the trust split intact (the cached origin is fetched with its own token, supplied through its fetch action; the source carries none). Under the default passthrough strategy only the anonymous public origin is cached, so in practice the cache holds one source per package; the dimension keeps the key honest about which upstream an entry is, never blurring the split.

A coherent cache entry: the parsed PackageInfo paired with the raw Value it was decoded from. A hit returns both, so a caller gets a typed view to decide over and the exact bytes that produced it: the packument serve path edits the raw Value in place and must keep its typed decision coherent with those bytes.

Estimate a CacheEntry's resident footprint in bytes as a fixed multiple of its raw document's compact-encoded byte length. The resident cost (the parsed PackageInfo plus the raw Value) is a near-constant multiple of the document's size, so re-encoding the raw Value and scaling it estimates the footprint without measuring the parsed structure. The encode is an O(document) pass run only on a leader's insert (the cold path after a fetch), never on a hit. The multiplier is set at the high end of the observed resident-to-encoded ratio so the estimate is an upper bound: a memory budget must not systematically under-count.

Resolve a package's metadata from one upstream Source, reusing the cache and collapsing concurrent misses.

On a fresh, unexpired hit the cached CacheEntry is returned and the fetch action is never run. On a miss the action runs exactly once even under concurrent callers: the first installs an in-flight marker and fetches, the others wait on its result. A successful fetch is cached (subject to the TTL and size bound); a failed fetch caches nothing (so a transient upstream error does not poison the cache) and is re-raised to every waiter.

A claimed in-flight slot is always eventually filled and de-registered, even if the leader is hit by an async exception (a request timeout, a killed handler thread) between claiming the slot and completing: the claim commits under a mask and the leader's run is handed straight to guardInFlight, which frees the slot on every exit and, on any exception before the marker is filled, hands that error to every waiting follower rather than leaving them parked forever. This closes the single-flight orphan window (without it, a cancelled leader would wedge that (source, package) key until restart). A follower's own wait on the marker stays interruptible.

The Source partitions the cache: distinct upstreams of the same package resolve under distinct keys and never cross-contaminate. The fetch action supplies the origin's own credential, so reading through one source never blurs another's trust posture. Under the default passthrough strategy only the anonymous public origin is resolved here: the trusted private origin is the per-client authority and is fetched per request, never cached, so a shared entry can never serve one client another's private document.

The result is always re-decided by the caller's rules on each request -- only the fetch+parse is memoised, never the verdict.

Each resolution records the ecluse.metadata_cache.requests hit/miss counter (a coalescing follower counts as a miss, like the leader it waits on), and a leader's insert refreshes the ecluse.metadata_cache.entries occupancy gauge and the ecluse.metadata_cache.resident_bytes residency gauge.

As resolveMetadata, but with a hook run on the leading thread at the single-flight claim → fetch-runner handoff: the window between the STM transaction committing the in-flight claim and the leader's exception guard taking ownership of the marker. It exists only so a test can deterministically park a leader in that window and cancel it there, exercising the orphan-window guarantee; production always passes pure () via resolveMetadata.

Look up a package's cached full-packument entry for one Source without fetching on a miss: the cache's read-only view, for inspection and tests. A Nothing is a miss or an expired entry; this never triggers a fetch and never collapses (use resolveMetadata for the serve path).

The number of full-packument entries currently held (including any not-yet-purged expired).

Resolve one version's PackageDetails (or its determined absence) from the single-version cache, leading a selective fetch on a miss and collapsing concurrent misses exactly as resolveMetadata does for the full packument. The cached value is the Maybe PackageDetails the fetch yields, so a version determined absent over sound metadata is cached as Nothing (a negative entry) and re-served without a re-fetch within the TTL.

This writes to the single-version store only, never the full-packument store, so a cold tarball gate's selective parse cannot materialise a whole packument into the shared full cache. Unlike resolveMetadata, the single-version store records no hit/miss counter; a leader's insert does refresh the single-version residency gauge (ecluse.metadata_cache.version.resident_bytes), so the byte budget that bounds both stores is observable on each.

As resolveVersion, with the single-flight claim → fetch-runner handoff hook resolveMetadataWith exposes, for the same orphan-window test (production passes pure () via resolveVersion).

Look up a single-version cached entry for one (source, package, version) without fetching on a miss: the version store's read-only view (the hybrid serve path's negative/ positive lookup before it leads a selective fetch). The outer Maybe is the cache hit/miss (an expired or absent entry is Nothing); the inner Maybe PackageDetails is the cached result (a version determined absent is a cached Just Nothing).

Resolve the assembled representation for one derived validator, leading the render (assemble + encode) on a miss and collapsing concurrent identical renders, exactly as resolveMetadata does for a fetch.

The key is the rendered derived ETag -- a content address over every input the served document is a function of -- so a hit is byte-for-byte the document this request's own inputs would deterministically produce: the store can never serve stale bytes (changed inputs miss by construction) and never crosses a client boundary (a different private view is a different key; see the module header). Under the TTL-zero configuration the store degrades to pure single-flight coalescing, the same behaviour as the sibling stores.

Like the single-version store it records no hit/miss counter; a leader's insert refreshes the ecluse.metadata_cache.assembled.resident_bytes residency gauge, so the byte budget's third occupant is observable alongside the other two.