Module cache

Expand description

Response caching — an ADDITIVE layer in front of resolve that NEVER weakens fail-closed. URNs are content-addressed → immutable → cacheable.

§What is safe to cache

Only VERIFIED Success bytes. An IntegrityFailure / Unreachable / NotFound / any error outcome is NEVER cached (a cached Unreachable would block recovery when the network returns; caching a failure is simply wrong).
Keyed by the content-addressed identity storeId:root:resourceKey:salt with the CONCRETE resolved root — never the raw request URN. A root-pinned URN is immutable; a rootless URN is cached under the root the resolve actually produced (from the node’s X-Dig-Root), so it can’t go stale when the store advances.

Memory (LRU, bounded): process-trusted — it only ever holds what THIS process already verified THIS run, so a memory hit may skip re-verification.
Disk (optional, native): UNTRUSTED storage. It caches the verifiable artifacts (ciphertext + inclusion proof + chunk lengths), NOT plaintext, so a disk hit is RE-VERIFIED against the URN’s chain-anchored root before use (see DiskArtifacts). A tampered on-disk file therefore FAILS verification → IntegrityFailure, and its bytes are never served. Filenames are the SHA-256 of the identity (content-addressed, no path-traversal from the URN).

DiskArtifacts: The verifiable artifacts of an rpc-path fetch — enough to RE-VERIFY the bytes from scratch against the URN’s root. Persisted to the disk cache so a disk hit is re-verified (never trusted blindly).
DiskCache: A content-addressed disk cache of DiskArtifacts. UNTRUSTED: every read is re-verified by the caller against the URN’s root before use.
MemoryCache: A bounded in-memory LRU of verified plaintext, keyed by content_id. Bounded by BOTH an entry count and a total-byte budget (this ends up in a wallet — no unbounded growth). Process-trusted: a hit returns without re-verification.

DEFAULT_MEMORY_BYTES: See DEFAULT_MEMORY_ENTRIES.
DEFAULT_MEMORY_ENTRIES: The default memory-cache bounds: 256 entries or 32 MiB, whichever binds first.

content_id: The content-addressed cache identity: storeId:root:resourceKey:salt. root MUST be the CONCRETE resolved root (pinned root, or the node’s X-Dig-Root).