@aephia/atlas-kit 0.4.0 → 0.6.0-next.1

package/dist/registry/index.js

@@ -1,10 +1,16 @@
+import { encodeDefinitionSectionSnapshot, hydrateDefinitionSectionSnapshot, } from './definition-section-snapshot.js';
+import { captureSectionRevisions, publishIfCurrent } from './publication.js';
+import { attachReadMeta, } from '../internal/read-meta.js';
+import { attachJsonSerialization, toJsonSafeValue } from '../internal/json.js';
+import { hydrateShipStats } from './ship-stats-snapshot.js';
 import { isAddress } from '@solana/kit';
-import { AccountNotFoundError, MissingGameContextError, ProviderError, RegistryOutOfSyncError, } from '../client/errors.js';
-import { assertContextActive } from '../client/lifecycle.js';
+import { AccountNotFoundError, MissingGameContextError, InvalidDefinitionSectionError, ProviderError, RegistryOutOfSyncError, } from '../client/errors.js';
+import { assertContextActive, waitForRegistry } from '../client/lifecycle.js';
 import { deepFreeze, validateImmutableTree, } from '../internal/immutable-tree.js';
 import { decodeGameRegistrySections, } from '../internal/c4/game.js';
 const SEQUENCE_MISMATCH_RETRY_DELAY_MS = 1_000;
-// Ship summaries expose stable identity fields; every other section is strict.
+// D029/D055 tolerate newer ship definitions for older callers; the resolved
+// definitionSequenceId exposes that skew. Every other section remains strict.
 const SECTIONS_TOLERATING_OLDER_CALLERS = new Set(['ships']);
 const registryStates = new WeakMap();
 function stateFor(context) {
@@ -15,7 +21,7 @@ function stateFor(context) {
             confirmedSequenceMismatches: {},
             confirmingMissing: new Set(),
             confirmingSequenceIds: {},
-            loading: {},
+            revisions: {},
             refresh: new Set(),
             sections: {},
         };
@@ -26,7 +32,33 @@ function stateFor(context) {
 function freezeDefinitions(definitions) {
     return Object.freeze(definitions.map((definition) => deepFreeze({ ...definition })));
 }
+function freezeShips(definitions, sequenceId) {
+    return Object.freeze(definitions.map((definition) => {
+        const value = deepFreeze({
+            ...definition,
+            definitionSequenceId: sequenceId,
+        });
+        return Object.freeze(attachJsonSerialization({ ...value }));
+    }));
+}
+function isPersistedDefinitionSection(section) {
+    return (section === 'claimStakes' ||
+        section === 'buildings' ||
+        section === 'craftingHabs' ||
+        section === 'habBuildings');
+}
+function freezeCatalog(data) {
+    const catalog = Object.freeze(data.definitions.map((definition) => Object.freeze(attachJsonSerialization({ ...deepFreeze(definition) }))));
+    return {
+        catalog,
+        definitions: new Map(catalog.map((definition) => [definition.id, definition])),
+        sequenceId: data.sequenceId,
+    };
+}
 function sectionFromGame(game, section) {
+    if (isPersistedDefinitionSection(section)) {
+        return freezeCatalog(game);
+    }
     if (section === 'xp') {
         const definitions = freezeDefinitions([
             game,
@@ -46,11 +78,13 @@ function sectionFromGame(game, section) {
     }
     if (section === 'ships') {
         const ships = game;
-        const definitions = freezeDefinitions(ships.definitions);
-        return {
+        const definitions = freezeShips(ships.definitions, ships.sequenceId);
+        const loaded = {
+            configurations: definitions,
             definitions: new Map(definitions.map((definition) => [definition.id, definition])),
             sequenceId: ships.sequenceId,
         };
+        return loaded;
     }
     const values = game;
     const definitions = freezeDefinitions(values.definitions);
@@ -84,8 +118,9 @@ function hasUniqueDefinitionIds(definitions) {
 }
 function isShipDefinition(value) {
     return (isRecord(value) &&
-        hasOwnKeyCount(value, 4) &&
+        hasOwnKeyCount(value, 5) &&
         isNonnegativeInteger(value.id) &&
+        value.id <= 65535 &&
         typeof value.mint === 'string' &&
         isAddress(value.mint) &&
         typeof value.name === 'string' &&
@@ -110,10 +145,11 @@ function isCompatibleSnapshot(snapshot, game, section) {
     }
     if (!isRecord(snapshot) ||
         !hasOwnKeyCount(snapshot, 5) ||
-        snapshot.schemaVersion !== 1 ||
+        snapshot.schemaVersion !== (section === 'ships' ? 2 : 1) ||
         snapshot.game !== game ||
         snapshot.section !== section ||
         !isNonnegativeInteger(snapshot.sequenceId) ||
+        (section === 'ships' && snapshot.sequenceId > 4294967295) ||
         !Array.isArray(snapshot.definitions)) {
         return false;
     }
@@ -125,18 +161,43 @@ function isCompatibleSnapshot(snapshot, game, section) {
         hasUniqueDefinitionIds(snapshot.definitions));
 }
 function snapshotFor(game, section, loaded) {
+    if (section === 'ships') {
+        return {
+            definitions: [...loaded.definitions.values()].map(({ id, mint, name, sizeClass, stats }) => ({
+                id,
+                mint,
+                name,
+                sizeClass,
+                stats: toJsonSafeValue(stats),
+            })),
+            game,
+            schemaVersion: 2,
+            section,
+            sequenceId: loaded.sequenceId,
+        };
+    }
     return {
-        definitions: [...loaded.definitions.values()],
+        definitions: [
+            ...loaded.definitions.values(),
+        ],
         game,
         schemaVersion: 1,
-        section,
+        section: 'cargo',
         sequenceId: loaded.sequenceId,
     };
 }
 function sectionFromSnapshot(snapshot) {
     if (snapshot.section === 'ships') {
-        const definitions = freezeDefinitions(snapshot.definitions);
+        const rows = [];
+        for (const definition of snapshot.definitions) {
+            const stats = hydrateShipStats(definition.stats);
+            if (stats === undefined)
+                return undefined;
+            rows.push({ ...definition, stats });
+        }
+        const definitions = freezeShips(rows, snapshot.sequenceId);
         return {
+            configurations: definitions,
             definitions: new Map(definitions.map((definition) => [definition.id, definition])),
             sequenceId: snapshot.sequenceId,
         };
@@ -148,35 +209,49 @@ function sectionFromSnapshot(snapshot) {
     };
 }
 async function loadStoredSection(context, game, section) {
-    // Snapshot schema v1 is JSON-native and intentionally excludes crafting
-    // sections whose exact public definitions contain bigint values.
-    if (section !== 'ships' && section !== 'cargo') {
+    assertContextActive(context);
+    if (section === 'xp' || section === 'research')
         return undefined;
-    }
     const store = context.registrySnapshotStore;
     if (store === undefined)
         return undefined;
+    let snapshot;
     try {
-        const snapshot = await store.load(game, section);
-        if (!isCompatibleSnapshot(snapshot, game, section)) {
-            return undefined;
-        }
-        return sectionFromSnapshot(snapshot);
+        snapshot = await store.load(game, section);
     }
     catch {
         throw new ProviderError(`The application registry snapshot store could not load the ${section} definitions. Repair or disable the snapshot store, then retry.`, { accountType: 'game', address: game });
     }
+    if (isPersistedDefinitionSection(section)) {
+        const hydrated = hydrateDefinitionSectionSnapshot(snapshot, game, section);
+        return hydrated === undefined
+            ? undefined
+            : freezeCatalog(hydrated);
+    }
+    if (!isCompatibleSnapshot(snapshot, game, section))
+        return undefined;
+    return sectionFromSnapshot(snapshot);
 }
 async function saveSection(context, game, section, loaded) {
-    // Keep the load/save boundary symmetric until a versioned bigint encoding
-    // extends DefinitionSectionSnapshot.
-    if (section !== 'ships' && section !== 'cargo')
+    assertContextActive(context);
+    if (section === 'xp' || section === 'research')
         return;
     const store = context.registrySnapshotStore;
     if (store === undefined)
         return;
     try {
-        if (section === 'ships') {
+        if (isPersistedDefinitionSection(section)) {
+            const definitions = loaded.definitions;
+            const snapshot = encodeDefinitionSectionSnapshot(game, section, {
+                definitions: [...definitions.values()],
+                sequenceId: loaded.sequenceId,
+            });
+            // Loaded Game projections have already passed the pinned section validator.
+            /* v8 ignore next -- the encoder also guards its typed boundary; incompatible inputs are covered in its dedicated tests. */
+            if (snapshot !== undefined)
+                await store.save(snapshot);
+        }
+        else if (section === 'ships') {
             await store.save(snapshotFor(game, section, loaded));
         }
         else {
@@ -188,122 +263,209 @@ async function saveSection(context, game, section, loaded) {
         // read remains authoritative when application-owned storage is unavailable.
     }
 }
+function publishSection(state, section, loaded) {
+    // Every caller pairs a candidate with the section that translated it.
+    state.sections[section] = loaded;
+    state.revisions[section] = (state.revisions[section] ?? 0) + 1;
+}
+function invalidateSection(state, section) {
+    // Resolver invalidation follows a successful publication, which initializes this revision.
+    state.revisions[section] = state.revisions[section] + 1;
+    state.refresh.add(section);
+}
 async function populateFromGame(context, game, sectionsToPopulate, state) {
-    const account = await context.data.readRaw(game);
+    const revisions = captureSectionRevisions(state.revisions, sectionsToPopulate);
+    const account = await waitForRegistry(context, context.data.readRaw(game));
+    assertContextActive(context);
     if (account === undefined)
         throw new AccountNotFoundError('game', game);
     const decoded = decodeGameRegistrySections(account, sectionsToPopulate);
     const populated = sectionsToPopulate.map((populatedSection) => {
         const loaded = (() => {
+            if (populatedSection === 'buildings') {
+                const buildings = sectionFromGame(decoded.buildings, 'buildings');
+                return buildings;
+            }
+            if (populatedSection === 'claimStakes') {
+                const claimStakes = sectionFromGame(decoded.claimStakes, 'claimStakes');
+                return claimStakes;
+            }
             if (populatedSection === 'ships') {
                 const ships = sectionFromGame(decoded.ships, 'ships');
-                state.sections.ships = ships;
                 return ships;
             }
             if (populatedSection === 'cargo') {
                 const cargo = sectionFromGame(decoded.cargo, 'cargo');
-                state.sections.cargo = cargo;
                 return cargo;
             }
             if (populatedSection === 'craftingHabs') {
                 const craftingHabs = sectionFromGame(decoded.craftingHabs, 'craftingHabs');
-                state.sections.craftingHabs = craftingHabs;
                 return craftingHabs;
             }
             if (populatedSection === 'habBuildings') {
                 const habBuildings = sectionFromGame(decoded.habBuildings, 'habBuildings');
-                state.sections.habBuildings = habBuildings;
                 return habBuildings;
             }
             if (populatedSection === 'xp') {
                 const xp = sectionFromGame(decoded.xp, 'xp');
-                state.sections.xp = xp;
                 return xp;
             }
             const research = sectionFromGame(decoded.research, 'research');
-            state.sections.research = research;
             return research;
         })();
-        const confirmingSequenceId = state.confirmingSequenceIds[populatedSection];
-        if (confirmingSequenceId !== undefined) {
-            state.confirmedSequenceMismatches[populatedSection] = {
-                actualSequenceId: loaded.sequenceId,
-                confirmedAtMonotonicMs: performance.now(),
-                expectedSequenceId: confirmingSequenceId,
-            };
-            delete state.confirmingSequenceIds[populatedSection];
-        }
-        else if (state.confirmedSequenceMismatches[populatedSection]?.actualSequenceId !==
-            loaded.sequenceId) {
-            delete state.confirmedSequenceMismatches[populatedSection];
-        }
-        if (state.confirmingMissing.has(populatedSection)) {
-            state.confirmedMissingSequenceIds[populatedSection] = loaded.sequenceId;
-            state.confirmingMissing.delete(populatedSection);
+        return {
+            loaded: {
+                ...loaded,
+                observation: Object.freeze({
+                    slot: account.slot,
+                    commitment: account.commitment,
+                }),
+            },
+            section: populatedSection,
+        };
+    });
+    assertContextActive(context);
+    const saves = [];
+    publishIfCurrent(state.revisions, revisions, () => {
+        for (const { loaded, section: populatedSection } of populated) {
+            publishSection(state, populatedSection, loaded);
+            const confirmingSequenceId = state.confirmingSequenceIds[populatedSection];
+            if (confirmingSequenceId !== undefined) {
+                state.confirmedSequenceMismatches[populatedSection] = {
+                    actualSequenceId: loaded.sequenceId,
+                    confirmedAtMonotonicMs: performance.now(),
+                    expectedSequenceId: confirmingSequenceId,
+                };
+                delete state.confirmingSequenceIds[populatedSection];
+            }
+            else if (state.confirmedSequenceMismatches[populatedSection]
+                ?.actualSequenceId !== loaded.sequenceId) {
+                delete state.confirmedSequenceMismatches[populatedSection];
+            }
+            if (state.confirmingMissing.has(populatedSection)) {
+                state.confirmedMissingSequenceIds[populatedSection] = loaded.sequenceId;
+                state.confirmingMissing.delete(populatedSection);
+            }
+            state.refresh.delete(populatedSection);
         }
-        state.refresh.delete(populatedSection);
-        return { loaded, section: populatedSection };
+        for (const { loaded, section } of populated)
+            saves.push(saveSection(context, game, section, loaded));
     });
-    await Promise.all(populated.map(({ loaded, section }) => saveSection(context, game, section, loaded)));
-}
-async function populateSection(context, game, section, state) {
-    if (!state.refresh.has(section)) {
-        const stored = await loadStoredSection(context, game, section);
-        if (stored !== undefined) {
-            if (section === 'ships')
-                state.sections.ships = stored;
-            else
-                state.sections.cargo = stored;
+    await waitForRegistry(context, Promise.all(saves));
+}
+async function populateSections(context, game, sections, state, fetchedTargets) {
+    const revisions = captureSectionRevisions(state.revisions, sections);
+    const stored = await waitForRegistry(context, Promise.all(sections.map(async (section) => state.refresh.has(section)
+        ? undefined
+        : loadStoredSection(context, game, section))));
+    assertContextActive(context);
+    for (const [index, section] of sections.entries()) {
+        const candidate = stored[index];
+        if (candidate !== undefined)
+            publishIfCurrent(state.revisions, [revisions[index]], () => publishSection(state, section, candidate));
+    }
+    const missing = sections.filter((section) => state.sections[section] === undefined || state.refresh.has(section));
+    if (missing.length > 0)
+        await populateFromGame(context, game, fetchedTargets.filter((section) => state.sections[section] === undefined || state.refresh.has(section)), state);
+}
+async function ensureSections(context, sections, lazyPair = false) {
+    const state = stateFor(context);
+    for (;;) {
+        assertContextActive(context);
+        const game = context.game;
+        if (game === undefined)
+            throw new MissingGameContextError();
+        const missing = sections.filter((section) => state.sections[section] === undefined || state.refresh.has(section));
+        if (missing.length === 0)
             return;
+        let group = state.gameLoading;
+        if (group === undefined) {
+            const targets = lazyPair &&
+                (missing[0] === 'ships' || missing[0] === 'cargo') &&
+                ((state.refresh.has('ships') && state.refresh.has('cargo')) ||
+                    (state.sections.ships === undefined &&
+                        state.sections.cargo === undefined))
+                ? ['ships', 'cargo']
+                : missing;
+            const promise = Promise.resolve()
+                .then(() => populateSections(context, game, missing, state, targets))
+                .finally(() => {
+                /* v8 ignore next -- serialization prevents replacement before settlement; retain identity-checked cleanup so a late completion can never clear newer work. */
+                if (state.gameLoading?.[0] === promise)
+                    delete state.gameLoading;
+            });
+            group = [promise, targets];
+            state.gameLoading = group;
         }
-    }
-    let gameLoading = state.gameLoading;
-    if (gameLoading === undefined) {
-        const sections = (section === 'ships' || section === 'cargo') &&
-            ((state.refresh.has('ships') && state.refresh.has('cargo')) ||
-                (state.sections.ships === undefined &&
-                    state.sections.cargo === undefined))
-            ? ['ships', 'cargo']
-            : [section];
-        const promise = populateFromGame(context, game, sections, state).finally(() => {
-            delete state.gameLoading;
-        });
-        gameLoading = [promise, sections];
-        state.gameLoading = gameLoading;
-    }
-    else if (!gameLoading[1].includes(section)) {
         try {
-            await gameLoading[0];
+            await waitForRegistry(context, group[0]);
         }
-        catch {
-            // An unrelated population cannot satisfy or fail this section. Retry
-            // after it settles so Game reads remain serialized.
+        catch (error) {
+            // Only unrelated work can fail independently of this request.
+            if (missing.some((section) => group[1].includes(section)))
+                throw error;
         }
-        return populateSection(context, game, section, state);
-    }
-    await gameLoading[0];
-    if (state.sections[section] === undefined || state.refresh.has(section)) {
-        return populateSection(context, game, section, state);
     }
 }
 async function ensureSection(context, section) {
+    await ensureSections(context, [section], true);
+    return stateFor(context).sections[section];
+}
+/** Warm selected definition catalogs, retaining each section's own observation.
+ * Already usable sections are reused; this is not a freshness refresh.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const loaded = await preloadDefinitions(ctx, ['ships', 'claimStakes']);
+ * const provenance = readMeta(loaded);
+ * ```
+ */
+export async function preloadDefinitions(context, sections, options = {}) {
     assertContextActive(context);
-    const game = context.game;
-    if (game === undefined)
-        throw new MissingGameContextError();
-    const state = stateFor(context);
-    const existing = state.sections[section];
-    if (existing !== undefined && !state.refresh.has(section))
-        return existing;
-    let loading = state.loading[section];
-    if (loading === undefined) {
-        loading = populateSection(context, game, section, state).finally(() => {
-            delete state.loading[section];
-        });
-        state.loading[section] = loading;
+    options.signal?.throwIfAborted();
+    if (!Array.isArray(sections))
+        throw new InvalidDefinitionSectionError();
+    const targets = [];
+    for (let index = 0; index < sections.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(sections, index);
+        const section = descriptor !== undefined && 'value' in descriptor
+            ? descriptor.value
+            : undefined;
+        if (typeof section !== 'string' ||
+            ![
+                'ships',
+                'cargo',
+                'buildings',
+                'claimStakes',
+                'craftingHabs',
+                'habBuildings',
+                'xp',
+                'research',
+            ].includes(section))
+            throw new InvalidDefinitionSectionError();
+        const supported = section;
+        if (!targets.includes(supported))
+            targets.push(supported);
     }
-    await loading;
-    return state.sections[section];
+    if (targets.length > 0)
+        await waitForRegistry(context, ensureSections(context, targets), options.signal);
+    assertContextActive(context);
+    const state = stateFor(context);
+    const metadata = {
+        kind: 'definition-preload',
+        sections: targets.map((section) => {
+            const loaded = state.sections[section];
+            return {
+                section,
+                sequenceId: loaded.sequenceId,
+                observation: loaded.observation === undefined
+                    ? { availability: 'unavailable' }
+                    : { availability: 'available', ...loaded.observation },
+            };
+        }),
+    };
+    deepFreeze(metadata);
+    return Object.freeze(attachReadMeta(targets, metadata));
 }
 async function resolveDefinition(context, section, id, options) {
     const loaded = await ensureSection(context, section);
@@ -321,7 +483,7 @@ async function resolveDefinition(context, section, id, options) {
                 performance.now() - confirmed.confirmedAtMonotonicMs >=
                     SEQUENCE_MISMATCH_RETRY_DELAY_MS) {
                 state.confirmingSequenceIds[section] = expected;
-                state.refresh.add(section);
+                invalidateSection(state, section);
             }
         }
         throw new RegistryOutOfSyncError(section, expected, loaded.sequenceId, id);
@@ -330,7 +492,7 @@ async function resolveDefinition(context, section, id, options) {
         const definitionMissingAfterRefresh = state.confirmedMissingSequenceIds[section] === loaded.sequenceId;
         if (!definitionMissingAfterRefresh && !toleratesOlderCaller) {
             state.confirmingMissing.add(section);
-            state.refresh.add(section);
+            invalidateSection(state, section);
         }
         throw new RegistryOutOfSyncError(section, expected, loaded.sequenceId, id, definitionMissingAfterRefresh);
     }
@@ -348,6 +510,71 @@ async function resolveDefinition(context, section, id, options) {
 export function resolveShip(context, shipId, options = {}) {
     return resolveDefinition(context, 'ships', shipId, options);
 }
+/** Lists every ship configuration in the context's loaded Game definitions section.
+ *
+ * Entries and the readonly array are retained for the section generation. Each
+ * entry is the same immutable object returned by `resolveShip`; loading either
+ * route serves the other without another Game read. A section refresh replaces
+ * the array and its entries together. Existing returned arrays remain immutable
+ * snapshots of their prior generation.
+ *
+ * `definitionSequenceId` identifies the loaded section, not proven-current chain
+ * state. This enumerates existing configurations without grouping by model or
+ * filling unallocated ids. The result has no guaranteed sorting order.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const configurations = await listShipConfigurations(ctx);
+ * for (const ship of configurations) {
+ *   console.log(ship.id, ship.name, ship.stats.cargo.cargoCapacity);
+ * }
+ * ```
+ */
+export async function listShipConfigurations(context) {
+    const loaded = (await ensureSection(context, 'ships'));
+    return loaded.configurations;
+}
+/** Lists current ship configurations associated with a mint in this context's Game.
+ *
+ * Groups by each configuration's on-chain `mint`, never display names, id ranges,
+ * or historical `mintToId` entries. Use a mint from the selected deployment;
+ * this does not map production mints to PTR or provide make/model labels or a
+ * default configuration. See `docs/research/ship-model-identity.md` (#395/#397).
+ *
+ * The frozen result shares objects with `resolveShip` and `listShipConfigurations`.
+ * A lazy index is retained with the ships section and replaced on section refresh;
+ * building it adds no RPC calls or metadata fetches. Unknown mints return a retained
+ * frozen empty array. Results have no guaranteed order or configuration count.
+ * `definitionSequenceId` denotes the loaded generation, not proven-current state.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const shipMint: Address;
+ * const configurations = await listShipConfigurationsByMint(ctx, shipMint);
+ * for (const ship of configurations) {
+ *   console.log(ship.id, ship.stats.cargo.cargoCapacity);
+ * }
+ * ```
+ */
+export async function listShipConfigurationsByMint(context, mint) {
+    const loaded = (await ensureSection(context, 'ships'));
+    if (loaded.mintIndex === undefined) {
+        const groups = new Map();
+        for (const ship of loaded.configurations) {
+            const group = groups.get(ship.mint);
+            if (group === undefined)
+                groups.set(ship.mint, [ship]);
+            else
+                group.push(ship);
+        }
+        for (const group of groups.values())
+            Object.freeze(group);
+        loaded.mintIndex = { groups, empty: Object.freeze([]) };
+    }
+    return loaded.mintIndex.groups.get(mint) ?? loaded.mintIndex.empty;
+}
 /** Resolves one cargo id to an immutable SDK-owned definition summary.
  *
  * @example
@@ -394,4 +621,48 @@ export async function listResearchDefinitions(context) {
     });
 }
 export { RegistryOutOfSyncError } from '../client/errors.js';
+/** Internal Claim Stake lookup using the shared section lifecycle. */
+export function resolveClaimStakeDefinition(context, id) {
+    return resolveDefinition(context, 'claimStakes', id, {});
+}
+/** Internal canonical Claim Stake catalog. */
+export async function listClaimStakeDefinitions(context) {
+    return (await ensureSection(context, 'claimStakes')).catalog;
+}
+/** Internal canonical Crafting Hab container catalog. */
+export async function listCraftingHabDefinitions(context) {
+    return (await ensureSection(context, 'craftingHabs')).catalog;
+}
+/** Internal Building definition lookup using the shared section lifecycle. */
+export function resolveClaimStakeBuildingDefinition(context, id) {
+    return resolveDefinition(context, 'buildings', id, {});
+}
+/** Internal canonical Claim Stake building catalog. */
+export async function listClaimStakeBuildingDefinitions(context) {
+    return (await ensureSection(context, 'buildings'))
+        .catalog;
+}
+/** Internal canonical Hab building catalog. */
+export async function listHabBuildingDefinitions(context) {
+    return (await ensureSection(context, 'habBuildings')).catalog;
+}
+/** Lists all cargo definitions from the context's retained Game section.
+ *
+ * The readonly array and its definitions are shared with by-id lookups for one
+ * section generation. A refresh replaces the array and id map together; old
+ * arrays remain immutable snapshots. Results have no guaranteed sorting order.
+ * Loading is lazy and may use a compatible cargo schema-v1 stored snapshot.
+ * The retained generation does not prove latest-chain freshness.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const definitions = await listCargoDefinitions(ctx);
+ * for (const cargo of definitions) console.log(cargo.id, cargo.name);
+ * ```
+ */
+export async function listCargoDefinitions(context) {
+    const loaded = (await ensureSection(context, 'cargo'));
+    return (loaded.catalog ??= Object.freeze([...loaded.definitions.values()]));
+}
 //# sourceMappingURL=index.js.map