@aephia/atlas-kit 0.0.0

package/dist/client/contracts.d.ts

@@ -0,0 +1,671 @@
+import type { Address as KitAddress, Commitment as KitCommitment, GetAccountInfoApi, GetBlockHeightApi, GetLatestBlockhashApi, GetMultipleAccountsApi, GetProgramAccountsApi, GetSignatureStatusesApi, Rpc, SendTransactionApi, SimulateTransactionApi } from '@solana/kit';
+import type { RegistrySnapshotStore } from '../registry/index.js';
+import type { SageSdkError } from './errors.js';
+/** A z.ink/Solana account address represented by `@solana/kit`.
+ *
+ * @example
+ * ```ts
+ * declare const profileAddress: Address;
+ * ```
+ */
+export type Address = KitAddress;
+/** A z.ink/Solana RPC commitment level.
+ *
+ * @example
+ * ```ts
+ * const commitment: Commitment = 'confirmed';
+ * ```
+ */
+export type Commitment = KitCommitment;
+/** The minimal Kit RPC surface used by the read-only z.ink provider.
+ *
+ * @example
+ * ```ts
+ * declare const rpc: SageRpc;
+ * const ctx = createSageContext({ cluster: 'zink-ptr', rpc });
+ * ```
+ */
+export type SageRpc = Rpc<GetAccountInfoApi & GetMultipleAccountsApi & GetProgramAccountsApi>;
+/** The minimal Kit RPC surface used for explicit write-side operations.
+ *
+ * Context creation only retains this transport; it never invokes it. Assembly
+ * uses it for blockhash lifetime, signer-free simulation, submission, and
+ * confirmation during explicit Plan operations.
+ *
+ * @example
+ * ```ts
+ * declare const rpc: SageRpc;
+ * declare const writeRpc: SageWriteRpc;
+ * const ctx = createSageContext({ cluster: 'zink-ptr', rpc, writeRpc });
+ * ```
+ */
+export type SageWriteRpc = Rpc<GetBlockHeightApi & GetLatestBlockhashApi & SimulateTransactionApi & SendTransactionApi & GetSignatureStatusesApi>;
+/** Stable account and gameplay entity identifiers used by cache keys and references.
+ *
+ * @example
+ * ```ts
+ * const type: EntityType = 'fleet';
+ * ```
+ */
+export type EntityType = 'game' | 'profile' | 'profileFaction' | 'character' | 'fleet' | 'fleetCrewBinding' | 'starSystem' | 'celestialBody' | 'starbasePlayer' | 'starbaseUpgradeProcess' | 'cargoPod' | 'claimStakeInstance' | 'recipe' | 'craftingHabInstance' | 'craftingProcess' | 'market' | 'marketOrder' | 'scanPattern' | 'loot' | 'outlawFlag' | 'atlasRewardRegistry' | 'atlasRewardConfig' | 'atlasRewardTreasury' | 'faction' | 'factionConfig' | 'factionEconomicsConfig' | 'factionRelationTracker' | 'factionStanding' | 'factionTreasury' | 'factionOwnership' | 'kingSystemTracker' | 'regionTracker' | 'loyaltyEpoch' | 'loyaltyContribution' | 'loyaltyAtlasBank';
+/** A known deployment preset supported by the installed SDK version.
+ *
+ * @example
+ * ```ts
+ * const cluster: KnownCluster = 'zink-ptr';
+ * ```
+ */
+export type KnownCluster = 'zink-ptr';
+/** An application-defined cluster identity.
+ *
+ * @example
+ * ```ts
+ * const cluster: CustomClusterIdentity = { name: 'local-fixture' };
+ * ```
+ */
+export interface CustomClusterIdentity {
+    readonly name: string;
+}
+/** Identity used to isolate context-owned caches and providers.
+ *
+ * @example
+ * ```ts
+ * const cluster: ClusterIdentity = { name: 'local-fixture' };
+ * ```
+ */
+export type ClusterIdentity = KnownCluster | CustomClusterIdentity;
+/** The source that supplied a raw account or translated snapshot.
+ *
+ * @example
+ * ```ts
+ * const source: DataSourceIdentity = { kind: 'fixture', name: 'unit-test' };
+ * ```
+ */
+export interface DataSourceIdentity {
+    readonly kind: 'rpc' | 'websocket' | 'indexer' | 'fixture' | 'application';
+    readonly name: string;
+}
+/** Raw, untrusted account bytes returned by a provider.
+ *
+ * @example
+ * ```ts
+ * declare const rawAccount: RawAccount;
+ * const bytes = rawAccount.data;
+ * ```
+ */
+export interface RawAccount {
+    readonly address: Address;
+    readonly owner: Address;
+    readonly lamports: bigint;
+    readonly data: Uint8Array;
+    readonly executable: boolean;
+    readonly slot: bigint;
+    readonly commitment: Commitment;
+}
+/** Options shared by direct and batched raw-account reads.
+ *
+ * @example
+ * ```ts
+ * const options: ReadAccountOptions = { commitment: 'confirmed' };
+ * ```
+ */
+export interface ReadAccountOptions {
+    readonly commitment?: Commitment;
+    readonly signal?: AbortSignal;
+}
+/** A verified byte comparison used for targeted program-account discovery.
+ *
+ * @example
+ * ```ts
+ * const filter: ProgramAccountFilter = { offset: 0, bytes: new Uint8Array([1]) };
+ * ```
+ */
+export interface ProgramAccountFilter {
+    readonly offset: number;
+    readonly bytes: Uint8Array;
+}
+/** A targeted program-account request using only adapter-verified offsets.
+ *
+ * @example
+ * ```ts
+ * declare const programAddress: Address;
+ * const request: ProgramAccountRequest = { programAddress, filters: [] };
+ * ```
+ */
+export interface ProgramAccountRequest extends ReadAccountOptions {
+    readonly programAddress: Address;
+    readonly filters: readonly ProgramAccountFilter[];
+}
+/** Address-only discovery request accepted by a replaceable indexer.
+ *
+ * Indexers return candidate addresses, never decoded domain state. The context
+ * validates every candidate through its direct account provider before a
+ * finder can expose it.
+ *
+ * @example
+ * ```ts
+ * declare const programAddress: Address;
+ * const request: IndexerDiscoveryRequest = {
+ *   accountType: 'fleet',
+ *   programAddress,
+ *   filters: [],
+ * };
+ * ```
+ */
+export interface IndexerDiscoveryRequest extends ProgramAccountRequest {
+    readonly accountType: EntityType;
+}
+/** Optional address-only provider for reverse and high-cardinality discovery.
+ *
+ * Implementations must treat `signal` as cancellation, preserve candidate
+ * order, and sanitize transport failures before throwing a `SageSdkError`.
+ * Duplicate addresses are allowed; the context deduplicates them before direct
+ * validation. A configured provider must support every account type and stable
+ * filter request that its context may issue. An empty result means the request
+ * is supported and has no candidates; it does not trigger RPC fallback. Use a
+ * separate context or the `direct`/`derived` strategies when indexer coverage is
+ * intentionally partial.
+ *
+ * @example
+ * ```ts
+ * const indexer: IndexerProvider = {
+ *   identity: { kind: 'indexer', name: 'application-indexer' },
+ *   discoverAddresses: async () => [],
+ * };
+ * ```
+ */
+export interface IndexerProvider {
+    readonly identity: DataSourceIdentity & {
+        readonly kind: 'indexer';
+    };
+    discoverAddresses(request: IndexerDiscoveryRequest): Promise<readonly Address[]>;
+}
+/** Address-only request accepted by a wallet-to-Profile discovery provider.
+ *
+ * The provider returns hints only. The identity domain directly reads every
+ * candidate Profile and verifies that its decoded key list contains the
+ * requested wallet before exposing it.
+ *
+ * @example
+ * ```ts
+ * declare const wallet: Address;
+ * const request: WalletProfileDiscoveryRequest = { wallet };
+ * ```
+ */
+export interface WalletProfileDiscoveryRequest extends ReadAccountOptions {
+    readonly wallet: Address;
+}
+/** Replaceable address-only provider for wallet-to-Profile discovery.
+ *
+ * Implementations may use an application index, service, or recorded mapping,
+ * but their output is never authoritative. They return Profile addresses only;
+ * the SDK validates account ownership, discriminator, shape, and the stored
+ * wallet-key relationship through its direct account provider. Duplicate and
+ * stale addresses are permitted and reported through finder metadata.
+ * Concurrent requests for the same wallet and commitment are single-flighted
+ * per context; cancelling one caller does not cancel the shared provider call.
+ * Shared operations are in-flight only: a settled failure is removed so a
+ * later request can retry the provider.
+ * Implementations must sanitize transport-specific causes before throwing a
+ * typed `SageSdkError`; unknown exceptions are normalized without their cause.
+ *
+ * @example
+ * ```ts
+ * const walletProfiles: WalletProfileDiscoveryProvider = {
+ *   identity: { kind: 'indexer', name: 'application-wallet-index' },
+ *   discoverProfileAddresses: async () => [],
+ * };
+ * ```
+ */
+export interface WalletProfileDiscoveryProvider {
+    readonly identity: DataSourceIdentity;
+    discoverProfileAddresses(request: WalletProfileDiscoveryRequest): Promise<readonly Address[]>;
+}
+/** Provider contract for raw z.ink account access.
+ *
+ * Provider results remain untrusted until an account definition validates and
+ * decodes them. Provider implementations must sanitize transport-specific
+ * causes before wrapping them in a typed `SageSdkError`; unknown exceptions are
+ * normalized by the data plane without retaining their raw cause.
+ *
+ * @example
+ * ```ts
+ * const provider: AccountProvider = {
+ *   identity: { kind: 'fixture', name: 'unit-test' },
+ *   readAccount: async () => undefined,
+ *   discoverAccounts: async () => [],
+ * };
+ * ```
+ */
+export interface AccountProvider {
+    readonly identity: DataSourceIdentity;
+    readAccount(address: Address, options?: ReadAccountOptions): Promise<RawAccount | undefined>;
+    /** Optional provider batching capability.
+     *
+     * Implementations preserve input order. Callers can fall back to ordered
+     * `readAccount` calls when a provider does not expose this transport method.
+     * Large reads can span multiple source slots because every RPC chunk records
+     * its own response context.
+     */
+    readAccounts?(addresses: readonly Address[], options?: ReadAccountOptions): Promise<readonly (RawAccount | undefined)[]>;
+    discoverAccounts(request: ProgramAccountRequest): Promise<readonly RawAccount[]>;
+}
+/** A context-owned raw-account subscription request.
+ *
+ * @example
+ * ```ts
+ * declare const address: Address;
+ * const request: AccountSubscriptionRequest = { address, commitment: 'confirmed' };
+ * ```
+ */
+export interface AccountSubscriptionRequest extends ReadAccountOptions {
+    readonly address: Address;
+}
+/** A raw account update or a transport reconnection boundary.
+ *
+ * Providers emit `reconnected` before post-reconnect account events so the
+ * context can close the missed-update gap through its direct provider.
+ *
+ * @example
+ * ```ts
+ * declare const account: RawAccount;
+ * const event: AccountSubscriptionEvent = { kind: 'account', account };
+ * ```
+ */
+export type AccountSubscriptionEvent = {
+    readonly kind: 'account';
+    readonly account: RawAccount;
+} | {
+    readonly kind: 'reconnected';
+};
+/** Provider-owned handle for one raw WebSocket registration.
+ *
+ * @example
+ * ```ts
+ * declare const registration: AccountSubscriptionRegistration;
+ * await registration.unsubscribe();
+ * ```
+ */
+export interface AccountSubscriptionRegistration {
+    unsubscribe(): Promise<void>;
+}
+/** Replaceable WebSocket provider used by a `SageContext`.
+ *
+ * The provider owns transport reconnection and emits a `reconnected` event
+ * after each successful re-registration. The context owns validation, cache
+ * updates, consumer notification, cancellation, and final disposal. Providers
+ * must apply bounded exponential backoff with jitter between reconnect attempts
+ * and must not emit `reconnected` for a failed attempt.
+ *
+ * @example
+ * ```ts
+ * const subscriptions: AccountSubscriptionProvider = {
+ *   identity: { kind: 'websocket', name: 'zink-ptr' },
+ *   subscribeAccount: async () => ({ unsubscribe: async () => undefined }),
+ * };
+ * ```
+ */
+export interface AccountSubscriptionProvider {
+    readonly identity: DataSourceIdentity;
+    subscribeAccount(request: AccountSubscriptionRequest, listener: (event: AccountSubscriptionEvent) => void): Promise<AccountSubscriptionRegistration>;
+}
+/** Adapter-owned definition for validating and decoding one account type.
+ *
+ * Decoded snapshots may contain primitives, arrays, and plain objects. Account
+ * definitions must normalize mutation-capable built-ins such as typed arrays,
+ * `Date`, `Map`, and `Set` to immutable domain values before returning them.
+ * The returned value must be an acyclic JSON-safe tree without `undefined`,
+ * symbol-keyed properties, accessors, or functions. Acyclic repeated object
+ * references are allowed and retain their identity in the frozen runtime tree.
+ * Each decoder receives an isolated copy of the untrusted provider account, so
+ * decoder mutation cannot affect another concurrent decoder or raw read.
+ * Decoders return plain data without methods. Public domain layers attach their
+ * required `toJSON()` method after reading through this port; returning a
+ * method from `decode` violates the immutable plain-data contract.
+ * A context reuses decoded cache entries only for the same definition object;
+ * distinct definitions cannot consume or overwrite each other's typed data.
+ * Keep definitions as stable module-level singletons. Reconstructing an
+ * equivalent definition for each call deliberately creates independent cache
+ * slots and prevents cache reuse.
+ *
+ * @example
+ * ```ts
+ * declare const programAddress: Address;
+ * const definition: AccountDefinition<{ name: string }> = {
+ *   type: 'fleet',
+ *   programAddress,
+ *   discriminator: new Uint8Array([1]),
+ *   minimumDataLength: 128,
+ *   decode: () => ({ name: 'Ravager' }),
+ * };
+ * ```
+ */
+export interface AccountDefinition<TSnapshot> {
+    readonly type: EntityType;
+    readonly programAddress: Address;
+    readonly discriminator: Uint8Array | readonly number[];
+    /** Optional positive safe-integer byte minimum enforced before decoding. */
+    readonly minimumDataLength?: number;
+    decode(account: RawAccount): Readonly<TSnapshot>;
+}
+/** A fully described immutable account snapshot plus its read provenance.
+ *
+ * @example
+ * ```ts
+ * declare const envelope: SnapshotEnvelope<unknown>;
+ * const slot = envelope.slot;
+ * const snapshot = envelope.data;
+ * ```
+ */
+export interface SnapshotEnvelope<TSnapshot> {
+    readonly data: Readonly<TSnapshot>;
+    readonly address: Address;
+    readonly programAddress: Address;
+    readonly accountType: EntityType;
+    readonly slot: bigint;
+    readonly commitment: Commitment;
+    readonly fetchedAt: number;
+    readonly source: DataSourceIdentity;
+    /** Returns a JSON-safe copy with every bigint represented as a decimal string. */
+    toJSON(): unknown;
+}
+/** Cache-first read controls for account and finder operations.
+ *
+ * @example
+ * ```ts
+ * const options: ReadOptions = { refresh: true, commitment: 'confirmed' };
+ * ```
+ */
+export interface ReadOptions extends ReadAccountOptions {
+    /** Bypasses a completed cache entry.
+     *
+     * A refresh may share a compatible provider request that is already in
+     * flight, because that request has not yet produced cached state.
+     */
+    readonly refresh?: boolean;
+    /** Maximum age of a completed cache entry in milliseconds.
+     *
+     * Overrides the context's `defaultMaxAgeMs`. Use `0` to always revalidate or
+     * `Infinity` to reuse completed cache entries until explicit invalidation.
+     */
+    readonly maxAgeMs?: number;
+    readonly policy?: 'cache-first' | 'no-store';
+}
+/** Strategies supported by generic account discovery requests.
+ *
+ * @example
+ * ```ts
+ * const strategy: AccountDiscoveryStrategy = 'targeted-program-accounts';
+ * ```
+ */
+export type AccountDiscoveryStrategy = 'direct' | 'derived' | 'indexer' | 'targeted-program-accounts' | 'broad-scan';
+/** Every strategy name exposed through public read metadata and errors.
+ *
+ * @example
+ * ```ts
+ * const strategy: DiscoveryStrategy = 'wallet-profile-provider';
+ * ```
+ */
+export type DiscoveryStrategy = AccountDiscoveryStrategy | 'known-addresses' | 'wallet-profile-provider';
+/** A discovery request supplied to the shared data port.
+ *
+ * Discovery always consults the provider, so direct-read freshness controls
+ * such as `refresh` and `maxAgeMs` are intentionally unavailable.
+ *
+ * @example
+ * ```ts
+ * const request: DiscoveryRequest = {
+ *   strategy: 'targeted-program-accounts',
+ *   filters: [],
+ * };
+ * ```
+ */
+export interface DiscoveryRequest extends ReadAccountOptions {
+    /** Controls whether validated discoveries populate the account cache. */
+    readonly policy?: 'cache-first' | 'no-store';
+    /** Selects the discovery behavior when no indexer takes precedence.
+     *
+     * When an indexer is configured, `targeted-program-accounts`, `broad-scan`,
+     * and `indexer` are advisory and use the indexer. Use `direct` or `derived`
+     * to bypass the indexer for a request.
+     */
+    readonly strategy: AccountDiscoveryStrategy;
+    readonly filters: readonly ProgramAccountFilter[];
+}
+/** Observer for validated snapshots and recoverable subscription errors.
+ *
+ * Malformed account events call `onError` without replacing the last valid
+ * cache entry or ending the subscription.
+ *
+ * @example
+ * ```ts
+ * const observer: SubscriptionObserver<{ name: string }> = {
+ *   onSnapshot: snapshot => console.log(snapshot.data.name),
+ *   onError: error => console.error(error),
+ * };
+ * ```
+ */
+export interface SubscriptionObserver<TSnapshot> {
+    readonly onSnapshot: (snapshot: SnapshotEnvelope<TSnapshot>) => void | Promise<void>;
+    readonly onError: (error: SageSdkError) => void | Promise<void>;
+    /** Observes bounded-delivery coalescing without treating it as an error. */
+    readonly onDiagnostic?: (event: SubscriptionDiagnosticEvent) => void;
+}
+/** A bounded-delivery diagnostic emitted by one account subscription.
+ *
+ * `coalescedCount` is cumulative for the currently pending observer delivery.
+ * Coalescing is expected under burst traffic and is never reported to
+ * `SubscriptionObserver.onError`.
+ *
+ * @example
+ * ```ts
+ * declare const address: Address;
+ * const event: SubscriptionDiagnosticEvent = {
+ *   kind: 'subscription-snapshot-coalesced',
+ *   accountType: 'fleet',
+ *   address,
+ *   coalescedCount: 2,
+ * };
+ * ```
+ */
+export type SubscriptionDiagnosticEvent = {
+    readonly kind: 'subscription-snapshot-coalesced';
+    readonly accountType: EntityType;
+    readonly address: Address;
+    readonly coalescedCount: number;
+} | {
+    readonly kind: 'subscription-error-coalesced';
+    readonly accountType: EntityType;
+    readonly address: Address;
+    readonly coalescedCount: number;
+    readonly errorCode: SageSdkError['code'];
+};
+/** Options for one context-owned subscription.
+ *
+ * @example
+ * ```ts
+ * const options: SubscriptionOptions = { commitment: 'confirmed' };
+ * ```
+ */
+export type SubscriptionOptions = ReadAccountOptions;
+/** Consumer handle for one context-owned subscription.
+ *
+ * Unsubscription is asynchronous, idempotent, and automatically performed by
+ * `SageContext.dispose()`. Teardown does not wait for an observer callback that
+ * is already running, so that callback may finish after teardown resolves.
+ *
+ * @example
+ * ```ts
+ * declare const subscription: SageSubscription;
+ * await subscription.unsubscribe();
+ * ```
+ */
+export interface SageSubscription {
+    unsubscribe(): Promise<void>;
+}
+/** Public read and discovery boundary shared by built-in domains and extensions.
+ *
+ * Cache entries are partitioned by stable account-definition object identity
+ * and may retain one view per commitment. They remain in memory until replaced,
+ * explicitly removed with `invalidate()`, or released when the owning context
+ * is disposed. The context rejects new cache keys above `maxCacheEntries`;
+ * callers can use `no-store` for intentional reads beyond that bound.
+ * Reconstructing definitions per call can therefore exhaust the configured
+ * capacity. Invalidation retains lightweight per-key generation barriers until
+ * context disposal so older in-flight reads and discoveries cannot repopulate
+ * a removed entry.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const definition: AccountDefinition<unknown>;
+ * declare const address: Address;
+ * const data: SageDataPort = ctx.data;
+ * const envelope = await data.read(definition, address);
+ * data.invalidate(definition, address);
+ * ```
+ */
+export interface SageDataPort {
+    /** Removes the exact cached account generation.
+     *
+     * Operations that started before invalidation may still resolve to their
+     * original callers, but cannot repopulate this cache entry or satisfy reads
+     * that start after invalidation.
+     */
+    invalidate<TSnapshot>(definition: AccountDefinition<TSnapshot>, address: Address): void;
+    read<TSnapshot>(definition: AccountDefinition<TSnapshot>, address: Address, options?: ReadOptions): Promise<SnapshotEnvelope<TSnapshot>>;
+    /** Reads addresses in input order.
+     *
+     * Context reads remain individually deduplicated. Uncached unique addresses
+     * use provider batching when available; direct-only providers use a bounded
+     * fallback worker pool.
+     */
+    readMany<TSnapshot>(definition: AccountDefinition<TSnapshot>, addresses: readonly Address[], options?: ReadOptions): Promise<readonly (SnapshotEnvelope<TSnapshot> | undefined)[]>;
+    discover<TSnapshot>(definition: AccountDefinition<TSnapshot>, request: DiscoveryRequest): Promise<readonly SnapshotEnvelope<TSnapshot>[]>;
+    /** Subscribes to one typed account and emits the selected cache view.
+     *
+     * Registration establishes the WebSocket listener first, then performs one
+     * direct read to close the registration race and emit current state. Valid
+     * stream updates use the same validation and cache path as direct reads. A
+     * failed initial read is reported through `onError`; it does not reject the
+     * subscription handle or end the registered stream.
+     */
+    subscribe<TSnapshot>(definition: AccountDefinition<TSnapshot>, address: Address, observer: SubscriptionObserver<TSnapshot>, options?: SubscriptionOptions): Promise<SageSubscription>;
+    readRaw(address: Address, options?: ReadAccountOptions): Promise<RawAccount | undefined>;
+}
+/** Immutable context passed as the first argument to every domain function.
+ *
+ * Disposing the context releases its cache and in-flight read registries.
+ *
+ * @example
+ * ```ts
+ * declare const rpc: SageRpc;
+ * const ctx: SageContext = createSageContext({ cluster: 'zink-ptr', rpc });
+ * ```
+ */
+export interface SageContext {
+    readonly cluster: ClusterIdentity;
+    readonly game?: Address;
+    readonly data: SageDataPort;
+    readonly registrySnapshotStore?: RegistrySnapshotStore;
+    readonly writeRpc?: SageWriteRpc;
+    dispose(): Promise<void>;
+}
+interface SharedContextOptions {
+    readonly commitment?: Commitment;
+    /** Default completed-cache freshness window in milliseconds.
+     *
+     * Defaults to 30,000. Individual reads can override it with
+     * `ReadOptions.maxAgeMs`; use `Infinity` to retain cache entries until
+     * explicit invalidation.
+     */
+    readonly defaultMaxAgeMs?: number;
+    readonly discovery?: {
+        readonly indexer?: IndexerProvider;
+        readonly walletProfiles?: WalletProfileDiscoveryProvider;
+    };
+    readonly game?: Address;
+    /** Maximum decoded bytes accepted for one untrusted account payload. */
+    readonly maxAccountDataBytes?: number;
+    /** Maximum number of address-keyed snapshots retained by this context. */
+    readonly maxCacheEntries?: number;
+    /** Maximum entries accepted from one RPC or indexer discovery response. */
+    readonly maxDiscoveryResults?: number;
+    /** Maximum input addresses accepted by one `readMany` call. */
+    readonly maxReadManyAccounts?: number;
+    readonly registrySnapshotStore?: RegistrySnapshotStore;
+    readonly subscriptions?: AccountSubscriptionProvider;
+    readonly writeRpc?: SageWriteRpc;
+}
+type ContextTransport = {
+    readonly rpc: SageRpc;
+    readonly provider?: never;
+} | {
+    readonly provider: AccountProvider;
+    readonly rpc?: never;
+};
+/** Configuration accepted by the synchronous context and client factories.
+ *
+ * Custom clusters require an explicit canonical Game address.
+ *
+ * @example
+ * ```ts
+ * declare const rpc: SageRpc;
+ * const options: SageContextOptions = { cluster: 'zink-ptr', rpc };
+ * ```
+ */
+export type SageContextOptions = (SharedContextOptions & ContextTransport & {
+    readonly cluster: KnownCluster;
+}) | (SharedContextOptions & ContextTransport & {
+    readonly cluster: CustomClusterIdentity;
+    readonly game: Address;
+});
+/** Address-keyed cache identity scoped to one context.
+ *
+ * @example
+ * ```ts
+ * declare const programAddress: Address;
+ * declare const address: Address;
+ * const key: CacheKey = { cluster: 'zink-ptr', programAddress, accountType: 'fleet', address };
+ * ```
+ */
+export interface CacheKey {
+    readonly cluster: ClusterIdentity;
+    readonly programAddress: Address;
+    readonly accountType: EntityType;
+    readonly address: Address;
+}
+/** Compatibility prototype; not the runtime cache representation.
+ *
+ * The shipped context owns its cache internally and does not expose cache
+ * records for inspection or mutation.
+ *
+ * @example
+ * ```ts
+ * declare const record: CacheRecord<unknown>;
+ * const snapshot = record.invalidated ? undefined : record.snapshot;
+ * ```
+ */
+export interface CacheRecord<TSnapshot> {
+    readonly key: CacheKey;
+    readonly snapshot: SnapshotEnvelope<TSnapshot>;
+    readonly invalidated: boolean;
+}
+/** Compatibility prototype; no context-wide diagnostic emitter ships.
+ *
+ * Shipped diagnostics are limited to finder provenance through `readMeta()` and
+ * subscription delivery events through `SubscriptionObserver.onDiagnostic`.
+ *
+ * @example
+ * ```ts
+ * const event: DiagnosticEvent = { kind: 'cache-hit', cluster: 'zink-ptr' };
+ * ```
+ */
+export interface DiagnosticEvent {
+    readonly kind: 'cache-hit' | 'cache-miss' | 'provider-read' | 'validation' | 'discovery';
+    readonly cluster: ClusterIdentity;
+    readonly address?: Address;
+    readonly accountType?: EntityType;
+}
+export {};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/client/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/client/contracts.ts"],"names":[],"mappings":"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"}

package/dist/client/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map