# Caching and provenance
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

> How snapshots are keyed, when they expire, and how to tell where a value came from.

Markdown source of https://develop.atlas-kit-docs.pages.dev/concepts/caching/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Account snapshots use an address-keyed cache. Game definition catalogs use a
separate context-owned registry with sequence-based generations. Understanding
that distinction lets you tune RPC traffic without assuming the same freshness
policy for both. See [Definition catalogs](/concepts/definitions/) for preload
and optional persistence.

## The cache key is an identity, not a call

Two reads of the same account through the same context return **the same
immutable snapshot** — not an equal copy, the same object — until it expires.

The key is: cluster identity, program address, account type, account address,
and the stable identity of the account definition used to decode it.

That last part matters more than it looks. Two decoders can never consume or
overwrite one another's data, because a different definition means a different
cache slot. It is why the SDK can hold several typed views of the same bytes
without them interfering.

The practical consequence: reading a fleet through `character.fleets.all()` and
reading the same fleet directly hits the same entry. You do not need to hoard
results yourself to avoid duplicate fetches.

## Freshness is a per-read decision

```ts
const sage = createSageClient({
  cluster: 'zink-ptr',
  rpc,
  defaultMaxAgeMs: 10_000,
});
```

That default applies to account reads unless a specific call overrides it.
It is not a refresh timer for retained Game definition catalogs. Raising it
cuts RPC traffic; lowering it costs requests. There is no universally right
value, because it depends on what you are reading — see the note on market data
in [markets](/guides/markets/).

## Commitment levels can coexist

Each typed slot may hold one snapshot per commitment level, so a lagging
stronger view and a newer weaker view can both be cached without fighting. A
read at a given commitment gets the snapshot for that commitment.

## Provenance answers "where did this come from?"

Use `readMeta()` to inspect available read metadata, including discovery
strategy and source slot/commitment. An observed slot records where a value came
from; it does not prove that the account has not changed since. Use the read
API's freshness controls when a current observation is needed.

Preloaded definition sections have their own per-section metadata. Restored
sections can explicitly report unavailable source provenance; there is no
single slot for a preload spanning several observations.

The [interactive examples](/start-here/first-read/) make this visible — running
two examples on one page, the second completes in a fraction of the time
because it reuses what the first fetched.

## Contexts are isolated

Two contexts are genuinely independent: separate caches, separate endpoints.
That is what makes it safe to run several in one process, and why creating a
context does no network work.

Reconstructing an equivalent account definition creates a separate cache
partition. Treat definitions as stable singletons instead of rebuilding them
for each call.

## Reference

- [`client`](/reference/client/) — context, cache, and provenance exports
- [How Atlas Kit reads the game](/start-here/how-it-thinks/) — the short version