# Definition catalogs
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.

> Reuse game configuration reads, preload selected catalogs, and persist them across sessions.

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

Definition catalogs describe game configuration: what a ship configuration,
building, or cargo type means. They are separate from observed account state,
such as a Fleet's current stats or an asteroid's mining counters.

## Read the catalog you need

These functions take your `ctx` as their first argument. Getters take a numeric
definition ID; listing functions return immutable arrays.

| Catalog               | Lookup                            | List                                | Entry point    |
| --------------------- | --------------------------------- | ----------------------------------- | -------------- |
| Ship configurations   | `resolveShip`                     | `listShipConfigurations`            | root           |
| Cargo                 | `getCargoDefinition`              | `listCargoDefinitions`              | `cargo`        |
| Claim Stakes          | `getClaimStakeDefinition`         | `listClaimStakeDefinitions`         | `claim-stakes` |
| Claim Stake buildings | `getClaimStakeBuildingDefinition` | `listClaimStakeBuildingDefinitions` | `claim-stakes` |
| Crafting Habs         | `getCraftingHabDefinition`        | `listCraftingHabDefinitions`        | `crafting`     |
| Hab buildings         | `getHabBuildingDefinition`        | `listHabBuildingDefinitions`        | `crafting`     |

Entry names are relative to `@aephia/atlas-kit`. Ship listing functions are also
available from `@aephia/atlas-kit/fleets`.
`listShipConfigurationsByMint(ctx, mint)` selects all configurations belonging
to one ship mint in the selected deployment. Configuration stats are distinct
from effective Fleet stats. See the [Fleet guide](/guides/fleets/).

Within a retained section generation, by-ID and listing routes reuse the same
canonical immutable definition objects. Repeating a listing reuses its frozen
array. There is no need to copy the catalog into a second application cache
just to avoid repeating a read.

The registry loads lazily from the Game account. Reading one catalog does not
retain every catalog. A later request for an unloaded section can therefore
require another Game fetch and decode. Lookups can check an expected section sequence and report
`RegistryOutOfSyncError` when the required generation is unavailable; an ahead
caller can invalidate the section for a subsequent reload. A sequence ID
identifies an observed generation; it does not prove that no newer on-chain
configuration exists. Account `defaultMaxAgeMs` is not a catalog refresh timer.

## Preload a known set of catalogs

Use the named root export when you know which catalogs a screen or job needs:

```ts
import { preloadDefinitions, readMeta } from '@aephia/atlas-kit';

const loaded = await preloadDefinitions(ctx, [
  'ships',
  'claimStakes',
  'buildings',
]);
for (const section of readMeta(loaded)!.sections) {
  console.log(section.section, section.sequenceId, section.observation);
}
```

Supported section names are `ships`, `cargo`, `claimStakes`, `buildings`,
`craftingHabs`, `habBuildings`, `xp`, and `research`. Preload uses the same
registry as lazy reads. Usable retained or compatible stored sections need no
new Game read. Missing selected sections share a validated Game fetch and
decode when they can load together; incompatible work already in flight can
require a subsequent read.

Preloading warms selected sections; it does not request freshness or promise
one observation shared by all sections. Inspect each section's metadata.
Restored sections without source provenance report `availability: 'unavailable'`
instead of inventing a slot or commitment. There is no aggregate slot.

## Optional persistence in browsers and Node.js

The default registry is in memory and belongs to its context. Applications can
supply an asynchronous `registrySnapshotStore` when creating the context to
retain supported sections across sessions. Implement the
[`RegistrySnapshotStore`](/reference/client/) contract with storage appropriate
to your application, such as IndexedDB in a browser or a file/database in a
Node.js tool. The shared SDK runtime does not import browser storage or Node.js
filesystem APIs.

Store the entire supplied section snapshot using its versioned JSON encoding;
do not strip its schema or sequence information or substitute a public
snapshot's `toJSON()` result.

| Section                           | Persisted encoding          |
| --------------------------------- | --------------------------- |
| Ships                             | Version 2                   |
| Cargo                             | Version 1                   |
| Claim Stakes and their buildings  | Separate version 2 sections |
| Crafting Habs and their buildings | Separate version 2 sections |
| XP and research                   | Not persisted               |

Incompatible or malformed stored sections are cache misses and reload lazily.
A store whose load operation throws produces a `ProviderError`; save failures
are best effort. A stored sequence is not evidence of current on-chain
freshness. Persistence of these catalogs does not provide generic restoration
of Fleet or world account snapshots.

## World and resource reads remain account reads

Star systems, planets, and asteroids use the address-keyed account cache and
its freshness controls. Resource projections reuse their body account; they
do not have a second catalog cache. A planet exposes resource richness, while
an asteroid also exposes changing `amountMined` and `miners` counters.
Preloading Game definitions does not fetch the galaxy.

See [Starmap](/guides/world/) for existing discovery routes and resource reads,
and [Caching and provenance](/concepts/caching/) for account freshness.