[santimattius]

Summary

• Add OkioCacheStorage(...) (stable) and KotlinxIoCacheStorage(...) (experimental) as public factories returning Ktor's CacheStorage.
• They plug straight into Ktor's own HttpCache { publicStorage(...) }, without the PersistentCache plugin, the shared facade or, for the kotlinx-io backend, Okio.
• Plugin config and both factories now take their defaults from one shared place.

Linked issue

Closes #75

Type of change

• Bug fix
• New feature
• Documentation
• Build / CI / tooling
• Breaking change

Changes

Area	Change
cache-core	CacheStorageDefaults (DIRECTORY, MAX_SIZE, TTL) behind @InternalPersistentCacheApi, used by PersistentCacheConfig and both factories
cache-okio	OkioCacheStorage(directory, maxSize, ttl, directoryProvider, fileSystem, clock), stable API
cache-kotlinx-io	KotlinxIoCacheStorage(...) with the same parameters, annotated @ExperimentalKotlinxIoCache
Build	cache-okio and cache-kotlinx-io now declare api(ktor-client-core) because the factories return Ktor's CacheStorage
Docs	README usage example, docs/STORAGE.md, CHANGELOG

Design decisions (from #75):

1. One factory per backend, with distinct names so both modules can share a classpath.
2. CacheFileSystem, CacheFileMetadata and FileCacheStorage stay behind the ERROR-level @InternalPersistentCacheApi. The factories do not leak it in their signatures.
3. Each factory inherits its backend's stability: Okio stable, kotlinx-io experimental.

Compatibility

• Additive public API only. apiDump baselines changed for the new declarations (JVM dumps for cache-okio and cache-kotlinx-io; JVM and klib dumps for cache-core).
• Consumers of cache-okio or cache-kotlinx-io now receive ktor-client-core transitively.
• PersistentCache behaviour and public API are unchanged.

Test plan

• ./gradlew assemble check apiCheck passes locally (macOS arm64, 6 GB Gradle heap)
• Each backend has 5 new tests using HttpCache and MockEngine with the factory directly: a second client on a fresh storage reads from disk with zero engine requests, defaults, custom directory, ttl, and maxSize eviction
• Those tests ran and passed on JVM, Android host (testAndroidHostTest) and iOS simulator; CacheStorageDefaultsTest adds 2 tests in cache-core
• Not run: Android device or emulator tests, Intel iOS tests, Windows and Linux

Checklist

• The linked issue is approved (status:approved)
• Commits follow Conventional Commits
• ./gradlew check apiCheck passes locally
• Tests were added or updated for behavior changes
• Public API changes are intentional and the baselines were updated with ./gradlew apiDump
• Documentation was updated where needed
• I have read CONTRIBUTING.md

Notes for reviewers

• PersistentCache does not call the backend factories, because cache-core cannot depend on the backends. It shares the FileCacheStorage algorithm and the defaults, so there is one code path for caching behaviour, but not one construction path. [Task]: Expose a public CacheStorage factory usable with Ktor HttpCache #75 asked for the plugin to build through the same factory; this is the closest the module layout allows.
• cache-okio and cache-kotlinx-io only have JVM API baselines (no .klib.api), so apiCheck guards only the JVM surface of the new factories.
• Test-first was followed strictly only for OkioCacheStorage; for the defaults object and KotlinxIoCacheStorage the implementation was written before the failing run. The kotlinx-io tests mirror the Okio ones.
• Review commit by commit: shared defaults, Okio factory, kotlinx-io factory, docs.