kedgeway

Docs / Reference / Data sources

Data sources

kedgeway does not ship a list of versions. Each run asks the Stellar Raven MCP server (https://raven.stellar.org/mcp) in a single call.

What it asks for

SourceUsed for
stellarDocs.get_doc_page on /docs/networks/software-versionsThe official Software Versions page: the current soroban-sdk, the current JavaScript SDK and the protocol version.
scout.analyzeEcosystem (toolchain)The Scout ecosystem toolchain index: a sample of repos on deprecated soroban-sdk versions.
stellarDocs.search_docsUpgrade and migration notes. The top five hits (title, URL, a short snippet) are collected into the snapshot. diagnose does not print them. migrate cites a hit only when its title or url is a migration document.

Which source wins

  • The official docs page is the authority for what is current.
  • Scout's deprecated list is a sample, capped at 50. A Scout entry only counts when it is below the current major from the docs.
  • A dependency more than one major behind is treated as deprecated even if Scout does not list it.

Provenance on every finding

Every finding cites its source and the time it was observed. The report header shows the current soroban-sdk major and the observation time, an ISO 8601 UTC timestamp taken when the run asked Raven.

DATA_DEGRADED

If a source fails or returns something kedgeway cannot read, the run does not stop and does not guess. It records a note, and each note becomes a DATA_DEGRADED finding. Notes name the source, for example:

  • stellarDocs.get_doc_page: <error>
  • software-versions: rust sdk row not found
  • scout.analyzeEcosystem: <error>
  • stellarDocs.search_docs: <error>

When the current soroban-sdk major is missing, repo findings fall back to SDK_UNKNOWN and no deprecation claim is made.

Snapshot cache

After every successful Raven fetch, kedgeway writes the ecosystem snapshot to $XDG_CACHE_HOME/kedgeway/snapshot.json (by default ~/.cache/kedgeway/, file mode 0600, folder 0700). Later runs reuse it.

SituationWhat happens
Fresh cacheYounger than --max-age (default 24h) and not dated in the future: used without calling Raven.
Stale cacheRefetched. If Raven then fails, the stale cache is used and a DATA_DEGRADED finding says using cached snapshot from <observedAt>.
--offlineNever calls Raven. Exits 1 if there is no cache. A stale cache is used with a DATA_DEGRADED finding such as snapshot is N hours old.
--no-cacheSkips reading the cache and the failure fallback, but still writes the fresh snapshot.
--max-age <duration>How old a cached snapshot may be: 30s, 15m, 24h or 2d.
  • A snapshot that carries DATA_DEGRADED notes is never written to the cache, and a cached one that carries notes counts as stale.
  • --offline with --no-cache is rejected (exit 1). --offline is ignored, with a warning, when --fixture is set. --fixture bypasses the cache entirely.
  • The cache is a single global file. --max-age applies to its observedAt.