docs(caching): the pingora cache engine is Enterprise-only and falls back silently

[claudespice]

Summary

#2186 added a caching.*.engine row and a "Choosing an engine" section to the OSS caching page, offering pingora as a plain selectable value alongside moka. Two things about it are missing:

1. It is not in the open source distribution. pingora is a Cargo feature, and it is absent from spiced's default feature list. Released images build --features release,models on top of default (release = []), so no published open source binary or image contains the Pingora backend at all — the whole module is behind #[cfg(feature = "pingora")]. Per the docs convention for capabilities gated out of the default build, this needs the Enterprise callout.

2. Selecting it on such a build is a silent downgrade, not an error. CacheEngine lives in spicepod and is not feature-gated, so engine: pingora parses everywhere. The dispatch then does:

CacheEngine::Pingora => {
    #[cfg(feature = "pingora")] { … PingoraBackend … }
    #[cfg(not(feature = "pingora"))] {
        tracing::warn!("{PINGORA_ENTERPRISE_ONLY_MESSAGE} Falling back to the Moka cache engine.");
        … CacheBackendEnum::MokaFallback(…)
    }
}

A user who reads the page, sets engine: pingora, and sees the runtime start normally is on Moka. MokaFallback also reports engine() as CacheEngine::Moka, so the startup line is the honest signal, which is why the note points at it rather than at the configured value.

3. pingora has no TinyLFU implementation. The same page documents eviction_policy: tiny_lfu; combined with engine: pingora it warns and uses LRU.

What changed

website/docs/features/caching/index.md only:

• engine row now says pingora requires an Enterprise build.
• The pingora bullet records that eviction_policy: tiny_lfu is not implemented there, quoting the warning.
• Added the standard :::note[Enterprise edition] callout with the verbatim fallback warning and the Initialized … cache; … engine: Moka startup line to check.

Both quoted strings are static format templates with no substituted fields, so they are greppable in a log exactly as written. The startup line does interpolate the configured size and TTL, which the text says explicitly.

Source refs (spiceai/spiceai @ 2f10331)

• crates/cache/src/lru_cache.rs#L53 — PINGORA_ENTERPRISE_ONLY_MESSAGE
• crates/cache/src/lru_cache.rs#L352-L382 — the engine dispatch, the TinyLFU warning, and the not(feature = "pingora") fallback arm
• bin/spiced/Cargo.toml — pingora = ["runtime/pingora"] is declared but not listed in default
• crates/runtime/src/init/caching.rs#L54 — Initialized sql results cache; {cache_provider}, whose Display ends in engine: {}

Scope

vNext only — the engine parameter is not documented in any versioned snapshot, so there is nothing to sweep. reference/distributions.md was left alone: its feature-gated section is scoped to data connectors, and widening it to cache engines is a structural change rather than an accuracy fix.

Test plan

• cd website && npm run build passes
• Cross-page grep: grep -rn "pingora" website/docs website/versioned_docs — the only non-acknowledgements hits are on this page
• Files updated: 1

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: claudespice

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🚀 deployed to https://91b82220.spiceai-org-website.pages.dev