The metadata cache's tunables, sourced from configuration: how long a parsed packument stays fresh, and each store's own StoreBudget. The three sub-budgets are carved from one cache aggregate at the composition root (Ecluse.Composition.MemoryBudget.budgetCacheConfig) and sum to it, so the cache's total resident bytes are bounded by the aggregate while each class's eviction pressure stays its own.

One store's bounds: the entry count and the resident-byte budget it keeps its held entries under before it evicts. Each entry is weighted by an estimate of its resident footprint, and an insert past the byte budget evicts the least-recently-used entries until the budget holds -- bounding memory more faithfully than the entry count alone.

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 but sized from its own sub-budget (the three used to share one bound, which tripled the intended cache footprint in the worst case).

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 document (CachedDoc) 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 rebuilds the served body from the raw document and must keep its typed decision coherent with those bytes. The store holds the raw document opaquely -- it never reads it, only weighs it (weighCachedDoc) and hands it back to the injected adapter capabilities.

Estimate a CacheEntry's resident footprint in bytes as a fixed multiple of its raw document's compact-encoded byte length (weighCachedDoc). The resident cost (the parsed PackageInfo plus the raw document) is a near-constant multiple of the document's size, so scaling the document's encoded length 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 its typed Left is handed to every waiter, so a coalesced follower sees exactly the fault the leader saw.

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 an escape 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 receiving an orphaned marker re-evaluates the resolve when the leader was cancelled (async), re-entering interruptibly and counting its miss only once, and re-raises when the leader escaped synchronously: the fetch's contract is total, so a synchronous escape is an invariant break for the outer boundary, never laundered into the typed channel. 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 and without bumping recency: the cache's read-only view. Two readers share it: the inspection and test probes, and the hybrid serve path's step-2 full-packument consult (the tarball gate selecting one version from a warm entry). That consult stays read-only on purpose: the full store's recency is driven by the packument GET's own resolveMetadata hit, so the gate's select need not bump it, unlike the single-version store whose only steady-state read is cachedVersion. A Nothing is a miss or an expired entry; this never triggers a fetch and never collapses (use resolveMetadata for the serve path).

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, bumping the entry's recency on a hit: the hybrid serve path's step-1 version consult before it leads a selective fetch. This read is the version store's only steady-state access (a hit here short-circuits before resolveVersion and its recency-bumping hit), so without the bump a warm version entry would never refresh its recency and would age out of the least-recently-used eviction in insert order. 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). Never fetches and never collapses (use resolveVersion to lead a selective fetch).

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.

The store's error slot is Void -- the render has no domain failure -- so the resolve is folded back to a plain IO ByteString here (absurd discharges the impossible Left), keeping the serve tail's call shape unchanged.