@aephia/atlas-kit 0.0.0

package/dist/client/context.js

@@ -0,0 +1,1374 @@
+import { isAddress } from '@solana/kit';
+import { AccountDecodeError, AccountNotFoundError, ContextDisposedError, InvalidAccountOwnerError, InvalidDerivationInputError, InvalidDiscriminatorError, MissingGameContextError, ProviderError, ResourceLimitExceededError, RelationshipNotDiscoverableError, SageSdkError, } from './errors.js';
+import { ProviderAccountAddressMismatchError } from './provider-errors.js';
+import { markContextDisposed } from './lifecycle.js';
+import { ZINK_PTR_GAME_ADDRESS } from './deployments.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { deepFreeze } from '../internal/immutable-tree.js';
+import { attachReadMeta } from '../internal/read-meta.js';
+import { createZinkProvider } from '../internal/zink/provider.js';
+import { INVALIDATE_CONTEXT_ADDRESSES, READ_CONTEXT_RAW_ACCOUNTS, } from './reconciliation.js';
+const DEFAULT_COMMITMENT = 'confirmed';
+const DEFAULT_MAX_AGE_MS = 30_000;
+const DEFAULT_MAX_ACCOUNT_DATA_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_CACHE_ENTRIES = 10_000;
+const DEFAULT_MAX_DISCOVERY_RESULTS = 10_000;
+const DEFAULT_MAX_READ_MANY_ACCOUNTS = 10_000;
+const MAX_CONCURRENT_FALLBACK_READS = 8;
+const RECONNECT_READ_COALESCE_MS = 250;
+const CONTEXT_DISCOVERY_RUNTIME = new WeakMap();
+const COMMITMENT_STRENGTH = {
+    processed: 0,
+    confirmed: 1,
+    finalized: 2,
+};
+const COMPATIBLE_COMMITMENTS = {
+    processed: ['processed', 'confirmed', 'finalized'],
+    confirmed: ['confirmed', 'finalized'],
+    finalized: ['finalized'],
+};
+class IndexerCandidateConflictError extends AccountDecodeError {
+}
+function clusterName(cluster) {
+    return typeof cluster === 'string' ? cluster : cluster.name;
+}
+function isProviderAddress(value) {
+    return (typeof value === 'string' &&
+        value.length >= 32 &&
+        value.length <= 44 &&
+        isAddress(value));
+}
+function isRawAccount(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const account = value;
+    return (isProviderAddress(account.address) &&
+        isProviderAddress(account.owner) &&
+        typeof account.lamports === 'bigint' &&
+        account.data instanceof Uint8Array &&
+        typeof account.data.byteLength === 'number' &&
+        typeof account.executable === 'boolean' &&
+        typeof account.slot === 'bigint' &&
+        (account.commitment === 'processed' ||
+            account.commitment === 'confirmed' ||
+            account.commitment === 'finalized'));
+}
+function cacheKey(cluster, definition, address, definitionId) {
+    return JSON.stringify([
+        clusterName(cluster),
+        definition.programAddress,
+        definition.type,
+        address,
+        definitionId,
+    ]);
+}
+function isPreferredSnapshot(candidate, current) {
+    return (candidate.slot > current.slot ||
+        (candidate.slot === current.slot &&
+            COMMITMENT_STRENGTH[candidate.commitment] >
+                COMMITMENT_STRENGTH[current.commitment]));
+}
+function isCompatible(available, requested) {
+    return COMMITMENT_STRENGTH[available] >= COMMITMENT_STRENGTH[requested];
+}
+function assertProviderCommitment(account, requested) {
+    if (!isCompatible(account.commitment, requested)) {
+        throw new ProviderError(`The configured provider returned ${account.commitment} data for a ${requested} request at ${account.address}. Fix the provider commitment handling before retrying.`, { address: account.address });
+    }
+}
+function copyProviderDiscoveryFilters(filters) {
+    return Object.freeze(filters.map((filter) => Object.freeze({
+        bytes: new Uint8Array(filter.bytes),
+        offset: filter.offset,
+    })));
+}
+function validateDiscoveryFilters(filters) {
+    for (const filter of filters) {
+        if (!Number.isSafeInteger(filter.offset) || filter.offset < 0) {
+            throw new InvalidDerivationInputError('Discovery filter offset', filter.offset, 'Use a nonnegative safe integer byte offset before discovering game accounts.');
+        }
+    }
+}
+function copyReadMetaFilters(filters) {
+    return Object.freeze(filters.map((filter) => Object.freeze({
+        bytes: Object.freeze([...filter.bytes]),
+        offset: filter.offset,
+    })));
+}
+function abortReason(signal) {
+    return signal.reason;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw abortReason(signal);
+    }
+}
+function assertWithinLimit(resource, actual, limit) {
+    if (actual > limit) {
+        throw new ResourceLimitExceededError(resource, actual, limit);
+    }
+}
+function configuredLimit(name, value, fallback) {
+    const selected = value ?? fallback;
+    if (!Number.isSafeInteger(selected) || selected < 1) {
+        throw new RangeError(`${name} must be a positive safe integer. Correct the context option before creating the SAGE context.`);
+    }
+    return selected;
+}
+function configuredMaxAgeMs(value) {
+    const selected = value ?? DEFAULT_MAX_AGE_MS;
+    if (selected !== Number.POSITIVE_INFINITY &&
+        (!Number.isFinite(selected) || selected < 0)) {
+        throw new InvalidDerivationInputError('Cache freshness maxAgeMs', selected, 'Use a nonnegative finite millisecond duration or Infinity before reading game state.');
+    }
+    return selected;
+}
+async function waitForCaller(promise, signal) {
+    if (signal === undefined) {
+        return promise;
+    }
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortReason(signal));
+        signal.addEventListener('abort', abort, { once: true });
+        void promise.then(resolve, reject).finally(() => {
+            signal.removeEventListener('abort', abort);
+        });
+    });
+}
+/** Internal context-owned bridge to the optional wallet discovery provider. */
+export async function discoverWalletProfileCandidates(context, wallet, options) {
+    const runtime = CONTEXT_DISCOVERY_RUNTIME.get(context);
+    if (runtime === undefined || runtime.walletProfiles === undefined) {
+        throw new RelationshipNotDiscoverableError('Wallet-to-Profile discovery is unavailable. Configure discovery.walletProfiles or pass known Profile addresses with strategy "known-addresses".', { accountType: 'profile', strategy: 'wallet-profile-provider' });
+    }
+    const walletProfiles = runtime.walletProfiles;
+    if (runtime.isDisposed())
+        throw new ContextDisposedError();
+    throwIfAborted(options?.signal);
+    const commitment = options?.commitment ?? runtime.defaultCommitment;
+    const callerSignal = options?.signal === undefined
+        ? runtime.lifecycle.signal
+        : AbortSignal.any([runtime.lifecycle.signal, options.signal]);
+    const discoveryKey = JSON.stringify([wallet, commitment]);
+    let operation = runtime.walletProfileDiscoveries.get(discoveryKey);
+    if (operation === undefined) {
+        let resolveDiscovery;
+        let rejectDiscovery;
+        operation = new Promise((resolve, reject) => {
+            resolveDiscovery = resolve;
+            rejectDiscovery = reject;
+        });
+        runtime.walletProfileDiscoveries.set(discoveryKey, operation);
+        const providerOperation = (async () => {
+            try {
+                const candidates = await walletProfiles.discoverProfileAddresses({
+                    commitment,
+                    signal: runtime.lifecycle.signal,
+                    wallet,
+                });
+                if (runtime.isDisposed())
+                    throw new ContextDisposedError();
+                if (!Array.isArray(candidates)) {
+                    throw new ProviderError('The configured wallet-to-Profile discovery provider returned malformed Profile addresses. Fix the provider response to return only valid z.ink/Solana addresses before retrying.', {
+                        accountType: 'profile',
+                        provider: walletProfiles.identity,
+                        strategy: 'wallet-profile-provider',
+                    });
+                }
+                assertWithinLimit('wallet Profile candidates', candidates.length, runtime.maxDiscoveryResults);
+                if (candidates.some((candidate) => typeof candidate !== 'string' || !isAddress(candidate))) {
+                    throw new ProviderError('The configured wallet-to-Profile discovery provider returned malformed Profile addresses. Fix the provider response to return only valid z.ink/Solana addresses before retrying discovery.', {
+                        accountType: 'profile',
+                        provider: walletProfiles.identity,
+                        strategy: 'wallet-profile-provider',
+                    });
+                }
+                return Object.freeze([...candidates]);
+            }
+            catch (cause) {
+                if (runtime.isDisposed())
+                    throw new ContextDisposedError();
+                if (cause instanceof SageSdkError)
+                    throw cause;
+                throw new ProviderError('The configured wallet-to-Profile discovery provider could not return Profile addresses. Check the provider connection and retry discovery.', {
+                    accountType: 'profile',
+                    provider: walletProfiles.identity,
+                    strategy: 'wallet-profile-provider',
+                });
+            }
+            finally {
+                if (runtime.walletProfileDiscoveries.get(discoveryKey) === operation) {
+                    runtime.walletProfileDiscoveries.delete(discoveryKey);
+                }
+            }
+        })();
+        void providerOperation.then(resolveDiscovery, rejectDiscovery);
+        void operation.catch(() => undefined);
+    }
+    return {
+        addresses: await waitForCaller(operation, callerSignal),
+        commitment,
+        source: Object.freeze({ ...walletProfiles.identity }),
+    };
+}
+/** Internal helper for collection metadata produced without a provider call. */
+export function contextCommitment(context, requested) {
+    return (requested ??
+        CONTEXT_DISCOVERY_RUNTIME.get(context)?.defaultCommitment ??
+        DEFAULT_COMMITMENT);
+}
+function validateAndDecode(definition, account, source, fetchedAt) {
+    if (account.owner !== definition.programAddress) {
+        throw new InvalidAccountOwnerError(definition.type, account.address, definition.programAddress, account.owner);
+    }
+    if (definition.discriminator.length === 0) {
+        throw new AccountDecodeError(definition.type, account.address, new TypeError('Account definitions require a non-empty discriminator. Fix the generated account definition before retrying.'));
+    }
+    const discriminatorMatches = account.data.length >= definition.discriminator.length &&
+        definition.discriminator.every((byte, index) => account.data[index] === byte);
+    if (!discriminatorMatches) {
+        throw new InvalidDiscriminatorError(definition.type, account.address);
+    }
+    const minimumDataLength = definition.minimumDataLength;
+    if (minimumDataLength !== undefined &&
+        (!Number.isSafeInteger(minimumDataLength) || minimumDataLength <= 0)) {
+        throw new AccountDecodeError(definition.type, account.address, new TypeError('Account definitions require minimumDataLength to be a positive safe integer. Fix the account definition before retrying.'));
+    }
+    if (minimumDataLength !== undefined &&
+        account.data.length < minimumDataLength) {
+        throw new AccountDecodeError(definition.type, account.address, new RangeError(`The ${definition.type} account requires at least ${String(minimumDataLength)} bytes before decoding, but the provider returned ${String(account.data.length)}.`));
+    }
+    let data;
+    try {
+        data = deepFreeze(definition.decode(account));
+    }
+    catch (cause) {
+        if (cause instanceof SageSdkError) {
+            throw cause;
+        }
+        throw new AccountDecodeError(definition.type, account.address, cause);
+    }
+    const envelope = {
+        accountType: definition.type,
+        address: account.address,
+        commitment: account.commitment,
+        data,
+        fetchedAt,
+        programAddress: definition.programAddress,
+        slot: account.slot,
+        source: deepFreeze({ ...source }),
+    };
+    return Object.freeze(attachJsonSerialization(envelope));
+}
+function copyRawAccount(account) {
+    return Object.freeze({
+        ...account,
+        data: new Uint8Array(account.data),
+    });
+}
+function createDataPort(cluster, provider, indexer, subscriptionProvider, defaultCommitment, defaultMaxAgeMs, isDisposed, lifecycle, maxAccountDataBytes, maxCacheEntries, maxDiscoveryResults, maxReadManyAccounts, trackSubscription) {
+    const cache = new Map();
+    const cacheKeysByAddress = new Map();
+    const activeCacheKeysByAddress = new Map();
+    const invalidatedAt = new Map();
+    const addressInvalidatedAt = new Map();
+    const discoveryInvalidatedAt = new Map();
+    const minimumRawReadSequence = new Map();
+    const minimumRawReadSequenceByAddress = new Map();
+    const definedReads = new Map();
+    const discoveryReads = new Map();
+    const indexerReads = new Map();
+    const rawReads = new Map();
+    const reconnectReads = new Map();
+    const snapshotFetchTimes = new WeakMap();
+    const definitionIds = new WeakMap();
+    let invalidationSequence = 0;
+    let reconciliationGeneration = 0;
+    let nextRawReadSequence = 0;
+    let nextDefinitionId = 0;
+    lifecycle.signal.addEventListener('abort', () => {
+        cache.clear();
+        cacheKeysByAddress.clear();
+        activeCacheKeysByAddress.clear();
+        invalidatedAt.clear();
+        addressInvalidatedAt.clear();
+        discoveryInvalidatedAt.clear();
+        minimumRawReadSequence.clear();
+        minimumRawReadSequenceByAddress.clear();
+        definedReads.clear();
+        discoveryReads.clear();
+        indexerReads.clear();
+        rawReads.clear();
+        reconnectReads.clear();
+    }, { once: true });
+    function assertActive() {
+        if (isDisposed()) {
+            throw new ContextDisposedError();
+        }
+    }
+    function assertAccountSize(account) {
+        if (!isRawAccount(account)) {
+            throw new ProviderError('The configured provider returned an invalid raw account. Fix the provider to return a complete account with valid z.ink/Solana address and owner fields and Uint8Array data before retrying.');
+        }
+        assertWithinLimit('account data bytes', account.data.byteLength, maxAccountDataBytes);
+    }
+    function requestedCommitment(options) {
+        return options?.commitment ?? defaultCommitment;
+    }
+    function definitionId(definition) {
+        const existing = definitionIds.get(definition);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const id = nextDefinitionId++;
+        definitionIds.set(definition, id);
+        return id;
+    }
+    function keyFor(definition, address) {
+        return cacheKey(cluster, definition, address, definitionId(definition));
+    }
+    function rememberCacheKey(key, address, programAddress) {
+        const keys = cacheKeysByAddress.get(address) ?? new Map();
+        keys.set(key, programAddress);
+        cacheKeysByAddress.set(address, keys);
+    }
+    function forgetCacheKey(key, address) {
+        const keys = cacheKeysByAddress.get(address);
+        keys?.delete(key);
+        if (keys?.size === 0)
+            cacheKeysByAddress.delete(address);
+    }
+    function rememberActiveCacheKey(key, address, programAddress) {
+        const keys = activeCacheKeysByAddress.get(address) ??
+            new Map();
+        const active = keys.get(key);
+        keys.set(key, {
+            count: (active?.count ?? 0) + 1,
+            programAddress,
+        });
+        activeCacheKeysByAddress.set(address, keys);
+    }
+    function forgetActiveCacheKey(key, address) {
+        const keys = activeCacheKeysByAddress.get(address);
+        const active = keys?.get(key);
+        if (active === undefined)
+            return;
+        if (active.count === 1)
+            keys?.delete(key);
+        else
+            keys?.set(key, { ...active, count: active.count - 1 });
+        if (keys?.size === 0)
+            activeCacheKeysByAddress.delete(address);
+    }
+    function validateAndTimestamp(definition, account, source) {
+        const fetchedAt = Date.now();
+        const fetchedAtMonotonicMs = performance.now();
+        const snapshot = validateAndDecode(definition, account, source, fetchedAt);
+        snapshotFetchTimes.set(snapshot, fetchedAtMonotonicMs);
+        return snapshot;
+    }
+    function rawReadKey(address, commitment) {
+        return JSON.stringify([address, commitment]);
+    }
+    function discoveryReadKey(programAddress, filters, commitment, invalidationGeneration, addressReconciliationGeneration) {
+        return JSON.stringify([
+            programAddress,
+            commitment,
+            invalidationGeneration,
+            addressReconciliationGeneration,
+            filters.map((filter) => [filter.offset, [...filter.bytes]]),
+        ]);
+    }
+    function definedReadKey(key, commitment, invalidationGeneration, store) {
+        return JSON.stringify([key, commitment, invalidationGeneration, store]);
+    }
+    function cachedSnapshot(key, commitment, options) {
+        if (options?.refresh === true || options?.policy === 'no-store') {
+            return undefined;
+        }
+        const cachedByCommitment = cache.get(key);
+        if (cachedByCommitment === undefined) {
+            return undefined;
+        }
+        const maxAgeMs = configuredMaxAgeMs(options?.maxAgeMs ?? defaultMaxAgeMs);
+        let selected;
+        for (const available of COMPATIBLE_COMMITMENTS[commitment]) {
+            const cached = cachedByCommitment.get(available);
+            if (cached === undefined ||
+                performance.now() - cached.fetchedAtMonotonicMs >= maxAgeMs) {
+                continue;
+            }
+            const snapshot = cached.snapshot;
+            if (selected === undefined || isPreferredSnapshot(snapshot, selected)) {
+                selected = snapshot;
+            }
+        }
+        return selected;
+    }
+    function sharedRawReadEntry(address, commitment, minimumSequence = 0) {
+        const effectiveMinimumSequence = Math.max(minimumSequence, minimumRawReadSequenceByAddress.get(address) ?? 0);
+        for (const available of COMPATIBLE_COMMITMENTS[commitment]) {
+            const compatible = rawReads.get(rawReadKey(address, available));
+            if (compatible !== undefined &&
+                compatible.sequence >= effectiveMinimumSequence) {
+                return compatible;
+            }
+        }
+        let resolveRead;
+        let rejectRead;
+        const promise = new Promise((resolve, reject) => {
+            resolveRead = resolve;
+            rejectRead = reject;
+        });
+        const read = {
+            sequence: nextRawReadSequence++,
+            promise,
+        };
+        const registryKey = rawReadKey(address, commitment);
+        rawReads.set(registryKey, read);
+        const operation = (async () => {
+            try {
+                const account = await provider.readAccount(address, {
+                    commitment,
+                    signal: lifecycle.signal,
+                });
+                if (isDisposed()) {
+                    throw new ContextDisposedError();
+                }
+                if (account !== undefined) {
+                    assertAccountSize(account);
+                    if (account.address !== address) {
+                        throw new ProviderAccountAddressMismatchError(address, account.address);
+                    }
+                    assertProviderCommitment(account, commitment);
+                }
+                return account;
+            }
+            catch (cause) {
+                if (isDisposed()) {
+                    throw new ContextDisposedError();
+                }
+                if (cause instanceof SageSdkError) {
+                    throw cause;
+                }
+                throw new ProviderError('The configured provider could not read the requested z.ink account. Check the provider connection and retry.', { address });
+            }
+            finally {
+                if (rawReads.get(registryKey) === read) {
+                    rawReads.delete(registryKey);
+                }
+            }
+        })();
+        void operation.then(resolveRead, rejectRead);
+        void promise.catch(() => undefined);
+        return read;
+    }
+    function sharedRawRead(address, commitment, minimumSequence = 0) {
+        return sharedRawReadEntry(address, commitment, minimumSequence).promise;
+    }
+    function findCompatibleRawRead(address, commitment, minimumSequence) {
+        const effectiveMinimumSequence = Math.max(minimumSequence, minimumRawReadSequenceByAddress.get(address) ?? 0);
+        for (const available of COMPATIBLE_COMMITMENTS[commitment]) {
+            const compatible = rawReads.get(rawReadKey(address, available));
+            if (compatible !== undefined &&
+                compatible.sequence >= effectiveMinimumSequence) {
+                return compatible;
+            }
+        }
+        return undefined;
+    }
+    function primeRawBatchReads(addresses, commitment, minimumSequenceFor) {
+        const pending = [...new Set(addresses)].filter((address) => findCompatibleRawRead(address, commitment, minimumSequenceFor(address)) === undefined);
+        if (pending.length === 0)
+            return;
+        const reads = pending.map((address) => {
+            let resolve;
+            let reject;
+            const promise = new Promise((accept, fail) => {
+                resolve = accept;
+                reject = fail;
+            });
+            const read = { promise, sequence: nextRawReadSequence++ };
+            rawReads.set(rawReadKey(address, commitment), read);
+            void promise.catch(() => undefined);
+            return { address, read, reject, resolve };
+        });
+        void (async () => {
+            try {
+                let accounts;
+                if (provider.readAccounts !== undefined) {
+                    const result = await provider.readAccounts(Object.freeze([...pending]), {
+                        commitment,
+                        signal: lifecycle.signal,
+                    });
+                    if (!Array.isArray(result) ||
+                        result.length !== pending.length ||
+                        !result.every((account) => account === undefined || isRawAccount(account))) {
+                        throw new ProviderError('The configured provider returned an invalid multiple-account response. Fix the provider to return undefined or a complete raw account for every requested address in the original order before retrying.');
+                    }
+                    accounts = result;
+                }
+                else {
+                    const fallback = new Array(pending.length);
+                    let nextIndex = 0;
+                    const worker = async () => {
+                        while (nextIndex < pending.length) {
+                            const index = nextIndex++;
+                            fallback[index] = await provider.readAccount(pending[index], {
+                                commitment,
+                                signal: lifecycle.signal,
+                            });
+                        }
+                    };
+                    await Promise.all(Array.from({
+                        length: Math.min(pending.length, MAX_CONCURRENT_FALLBACK_READS),
+                    }, worker));
+                    accounts = fallback;
+                }
+                if (isDisposed())
+                    throw new ContextDisposedError();
+                accounts.forEach((account, index) => {
+                    if (account === undefined)
+                        return;
+                    assertAccountSize(account);
+                    const requestedAddress = pending[index];
+                    if (account.address !== requestedAddress) {
+                        throw new ProviderAccountAddressMismatchError(requestedAddress, account.address);
+                    }
+                    assertProviderCommitment(account, commitment);
+                });
+                reads.forEach(({ resolve }, index) => resolve(accounts[index]));
+            }
+            catch (cause) {
+                const error = isDisposed()
+                    ? new ContextDisposedError()
+                    : cause instanceof SageSdkError
+                        ? cause
+                        : new ProviderError('The configured provider could not read the requested z.ink accounts. Check the provider connection and retry.');
+                reads.forEach(({ reject }) => reject(error));
+            }
+            finally {
+                reads.forEach(({ address, read }) => {
+                    const registryKey = rawReadKey(address, commitment);
+                    if (rawReads.get(registryKey) === read)
+                        rawReads.delete(registryKey);
+                });
+            }
+        })();
+    }
+    function sharedDiscovery(programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration) {
+        const registryKey = discoveryReadKey(programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration);
+        const existing = discoveryReads.get(registryKey);
+        if (existing !== undefined) {
+            return existing;
+        }
+        let resolveDiscovery;
+        let rejectDiscovery;
+        const promise = new Promise((resolve, reject) => {
+            resolveDiscovery = resolve;
+            rejectDiscovery = reject;
+        });
+        const read = {
+            promise,
+        };
+        discoveryReads.set(registryKey, read);
+        const operation = (async () => {
+            try {
+                const result = await provider.discoverAccounts({
+                    commitment,
+                    filters: copyProviderDiscoveryFilters(filters),
+                    programAddress,
+                    signal: lifecycle.signal,
+                });
+                if (isDisposed()) {
+                    throw new ContextDisposedError();
+                }
+                if (!Array.isArray(result)) {
+                    throw new ProviderError('The configured provider returned an invalid account-discovery response. Fix the provider to return a raw-account array before retrying.');
+                }
+                assertWithinLimit('discovery results', result.length, maxDiscoveryResults);
+                result.forEach(assertAccountSize);
+                return result;
+            }
+            finally {
+                if (discoveryReads.get(registryKey) === read) {
+                    discoveryReads.delete(registryKey);
+                }
+            }
+        })();
+        void operation.then(resolveDiscovery, rejectDiscovery);
+        void promise.catch(() => undefined);
+        return read;
+    }
+    function sharedIndexerDiscovery(activeIndexer, definition, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration) {
+        const registryKey = JSON.stringify([
+            'indexer',
+            definition.type,
+            discoveryReadKey(definition.programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration),
+        ]);
+        const existing = indexerReads.get(registryKey);
+        if (existing !== undefined)
+            return existing;
+        let resolveDiscovery;
+        let rejectDiscovery;
+        const promise = new Promise((resolve, reject) => {
+            resolveDiscovery = resolve;
+            rejectDiscovery = reject;
+        });
+        indexerReads.set(registryKey, promise);
+        const operation = (async () => {
+            try {
+                const candidates = await activeIndexer.discoverAddresses({
+                    accountType: definition.type,
+                    commitment,
+                    filters: copyProviderDiscoveryFilters(filters),
+                    programAddress: definition.programAddress,
+                    signal: lifecycle.signal,
+                });
+                if (isDisposed())
+                    throw new ContextDisposedError();
+                if (!Array.isArray(candidates)) {
+                    throw new ProviderError('The configured indexer returned malformed candidate addresses. Fix the indexer response to return only valid z.ink/Solana addresses before retrying discovery.', {
+                        accountType: definition.type,
+                        provider: activeIndexer.identity,
+                        strategy: 'indexer',
+                    });
+                }
+                assertWithinLimit('indexer candidates', candidates.length, maxDiscoveryResults);
+                if (candidates.some((candidate) => typeof candidate !== 'string' || !isAddress(candidate))) {
+                    throw new ProviderError('The configured indexer returned malformed candidate addresses. Fix the indexer response to return only valid z.ink/Solana addresses before retrying discovery.', {
+                        accountType: definition.type,
+                        provider: activeIndexer.identity,
+                        strategy: 'indexer',
+                    });
+                }
+                return Object.freeze([...candidates]);
+            }
+            catch (cause) {
+                if (isDisposed())
+                    throw new ContextDisposedError();
+                if (cause instanceof SageSdkError)
+                    throw cause;
+                throw new ProviderError('The configured indexer could not discover candidate addresses. Check the indexer connection and retry discovery.', {
+                    accountType: definition.type,
+                    provider: activeIndexer.identity,
+                    strategy: 'indexer',
+                });
+            }
+            finally {
+                if (indexerReads.get(registryKey) === promise) {
+                    indexerReads.delete(registryKey);
+                }
+            }
+        })();
+        void operation.then(resolveDiscovery, rejectDiscovery);
+        void promise.catch(() => undefined);
+        return promise;
+    }
+    async function validateIndexerCandidate(definition, address, filters, commitment, signal) {
+        const account = await waitForCaller(sharedRawRead(address, commitment, minimumRawReadSequence.get(keyFor(definition, address))), signal);
+        if (account === undefined)
+            return undefined;
+        const conflicts = filters.some((filter) => filter.offset + filter.bytes.length > account.data.length ||
+            filter.bytes.some((byte, index) => account.data[filter.offset + index] !== byte));
+        if (conflicts) {
+            throw new IndexerCandidateConflictError(definition.type, address, new RangeError('The directly read account bytes contradicted the indexer discovery filters.'), `The indexer returned ${address}, but its direct z.ink account state no longer matches the requested ${definition.type} relationship. Refresh the indexer or use targeted RPC discovery before retrying.`);
+        }
+        return validateAndTimestamp(definition, copyRawAccount(account), provider.identity);
+    }
+    function storeSnapshot(key, snapshot, operationInvalidationSequence) {
+        if ((invalidatedAt.get(key) ?? 0) > operationInvalidationSequence ||
+            (addressInvalidatedAt.get(snapshot.address) ?? 0) >
+                operationInvalidationSequence) {
+            return;
+        }
+        let cachedByCommitment = cache.get(key);
+        if (cachedByCommitment === undefined) {
+            assertWithinLimit('cache entries', cache.size + 1, maxCacheEntries);
+            cachedByCommitment = new Map();
+            cache.set(key, cachedByCommitment);
+            rememberCacheKey(key, snapshot.address, snapshot.programAddress);
+        }
+        const existing = cachedByCommitment.get(snapshot.commitment);
+        if (existing === undefined || snapshot.slot >= existing.snapshot.slot) {
+            cachedByCommitment.set(snapshot.commitment, {
+                fetchedAtMonotonicMs: snapshotFetchTimes.get(snapshot),
+                snapshot,
+            });
+        }
+    }
+    function assertCacheCapacity(keys) {
+        const additional = new Set(keys.filter((key) => !cache.has(key))).size;
+        assertWithinLimit('cache entries', cache.size + additional, maxCacheEntries);
+    }
+    function storeSubscriptionSnapshot(key, snapshot) {
+        const cachedByCommitment = cache.get(key);
+        if (invalidatedAt.has(key) &&
+            !cachedByCommitment?.has(snapshot.commitment)) {
+            return;
+        }
+        let writableByCommitment = cachedByCommitment;
+        if (writableByCommitment === undefined) {
+            assertWithinLimit('cache entries', cache.size + 1, maxCacheEntries);
+            writableByCommitment = new Map();
+            cache.set(key, writableByCommitment);
+            rememberCacheKey(key, snapshot.address, snapshot.programAddress);
+        }
+        const existing = writableByCommitment.get(snapshot.commitment);
+        if (existing === undefined || snapshot.slot > existing.snapshot.slot) {
+            writableByCommitment.set(snapshot.commitment, {
+                fetchedAtMonotonicMs: snapshotFetchTimes.get(snapshot),
+                snapshot,
+            });
+        }
+    }
+    function sharedDefinedRead(definition, address, commitment, store, minimumReadSequence = 0) {
+        const key = keyFor(definition, address);
+        const invalidationGeneration = invalidatedAt.get(key) ?? 0;
+        for (const available of COMPATIBLE_COMMITMENTS[commitment]) {
+            const compatible = definedReads.get(definedReadKey(key, available, invalidationGeneration, store));
+            if (compatible !== undefined &&
+                compatible.rawReadSequence >= minimumReadSequence) {
+                return compatible.promise;
+            }
+        }
+        const rawRead = sharedRawReadEntry(address, commitment, Math.max(minimumReadSequence, minimumRawReadSequence.get(key) ?? 0));
+        let resolveRead;
+        let rejectRead;
+        const promise = new Promise((resolve, reject) => {
+            resolveRead = resolve;
+            rejectRead = reject;
+        });
+        const read = {
+            promise,
+            rawReadSequence: rawRead.sequence,
+        };
+        const registryKey = definedReadKey(key, commitment, invalidationGeneration, store);
+        definedReads.set(registryKey, read);
+        rememberActiveCacheKey(key, address, definition.programAddress);
+        const operationInvalidationSequence = invalidationSequence;
+        const operation = (async () => {
+            try {
+                const raw = await rawRead.promise;
+                if (raw === undefined) {
+                    return undefined;
+                }
+                const snapshot = validateAndTimestamp(definition, copyRawAccount(raw), provider.identity);
+                if (store) {
+                    storeSnapshot(key, snapshot, operationInvalidationSequence);
+                }
+                return snapshot;
+            }
+            finally {
+                forgetActiveCacheKey(key, address);
+                if (definedReads.get(registryKey) === read) {
+                    definedReads.delete(registryKey);
+                }
+            }
+        })();
+        void operation.then(resolveRead, rejectRead);
+        void promise.catch(() => undefined);
+        return promise;
+    }
+    function sharedReconnectRead(definition, address, commitment) {
+        const key = keyFor(definition, address);
+        const registryKey = JSON.stringify([
+            key,
+            commitment,
+            invalidatedAt.get(key) ?? 0,
+        ]);
+        const existing = reconnectReads.get(registryKey);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const promise = sharedDefinedRead(definition, address, commitment, true);
+        reconnectReads.set(registryKey, promise);
+        const retainSettledResult = () => {
+            setTimeout(() => reconnectReads.delete(registryKey), RECONNECT_READ_COALESCE_MS);
+        };
+        void promise.then(retainSettledResult, retainSettledResult);
+        return promise;
+    }
+    async function readOptional(definition, address, options) {
+        assertActive();
+        throwIfAborted(options?.signal);
+        configuredMaxAgeMs(options?.maxAgeMs ?? defaultMaxAgeMs);
+        const commitment = requestedCommitment(options);
+        const key = keyFor(definition, address);
+        const cached = cachedSnapshot(key, commitment, options);
+        if (cached !== undefined) {
+            return cached;
+        }
+        return waitForCaller(sharedDefinedRead(definition, address, commitment, options?.policy !== 'no-store'), options?.signal);
+    }
+    function invalidateKey(key, address, programAddress) {
+        cache.delete(key);
+        forgetCacheKey(key, address);
+        invalidationSequence += 1;
+        invalidatedAt.set(key, invalidationSequence);
+        discoveryInvalidatedAt.set(programAddress, invalidationSequence);
+        minimumRawReadSequence.set(key, nextRawReadSequence);
+    }
+    return Object.freeze({
+        [INVALIDATE_CONTEXT_ADDRESSES](addresses) {
+            assertActive();
+            const uniqueAddresses = new Set(addresses);
+            reconciliationGeneration += 1;
+            for (const address of uniqueAddresses) {
+                invalidationSequence += 1;
+                addressInvalidatedAt.set(address, invalidationSequence);
+                minimumRawReadSequenceByAddress.set(address, nextRawReadSequence);
+                const keys = new Map(cacheKeysByAddress.get(address) ?? []);
+                for (const [key, active] of activeCacheKeysByAddress.get(address) ??
+                    []) {
+                    keys.set(key, active.programAddress);
+                }
+                for (const [key, programAddress] of keys) {
+                    invalidateKey(key, address, programAddress);
+                }
+            }
+        },
+        async [READ_CONTEXT_RAW_ACCOUNTS](addresses, options) {
+            assertActive();
+            throwIfAborted(options?.signal);
+            assertWithinLimit('readMany accounts', addresses.length, maxReadManyAccounts);
+            const commitment = requestedCommitment(options);
+            const unique = [...new Set(addresses)];
+            const minimumReadSequence = nextRawReadSequence;
+            primeRawBatchReads(unique, commitment, () => minimumReadSequence);
+            const accounts = new Map(await Promise.all(unique.map(async (address) => Object.freeze([
+                address,
+                await waitForCaller(sharedRawRead(address, commitment, minimumReadSequence), options?.signal),
+            ]))));
+            return Object.freeze(addresses.map((address) => {
+                const account = accounts.get(address);
+                return account === undefined ? undefined : copyRawAccount(account);
+            }));
+        },
+        invalidate(definition, address) {
+            assertActive();
+            const key = keyFor(definition, address);
+            invalidateKey(key, address, definition.programAddress);
+        },
+        async read(definition, address, options) {
+            const snapshot = await readOptional(definition, address, options);
+            if (snapshot === undefined) {
+                throw new AccountNotFoundError(definition.type, address);
+            }
+            return snapshot;
+        },
+        async readMany(definition, addresses, options) {
+            assertActive();
+            throwIfAborted(options?.signal);
+            assertWithinLimit('readMany accounts', addresses.length, maxReadManyAccounts);
+            configuredMaxAgeMs(options?.maxAgeMs ?? defaultMaxAgeMs);
+            const commitment = requestedCommitment(options);
+            const uncached = [...new Set(addresses)].filter((address) => cachedSnapshot(keyFor(definition, address), commitment, options) === undefined);
+            primeRawBatchReads(uncached, commitment, (candidate) => minimumRawReadSequence.get(keyFor(definition, candidate)) ?? 0);
+            return Object.freeze(await Promise.all(addresses.map((address) => readOptional(definition, address, options))));
+        },
+        async discover(definition, request) {
+            assertActive();
+            throwIfAborted(request.signal);
+            const operationInvalidationSequence = invalidationSequence;
+            const commitment = requestedCommitment(request);
+            validateDiscoveryFilters(request.filters);
+            const providerFilters = copyProviderDiscoveryFilters(request.filters);
+            const metadataFilters = copyReadMetaFilters(request.filters);
+            if (indexer !== undefined &&
+                request.strategy !== 'direct' &&
+                request.strategy !== 'derived') {
+                const candidates = await waitForCaller(sharedIndexerDiscovery(indexer, definition, providerFilters, commitment, discoveryInvalidatedAt.get(definition.programAddress) ?? 0, reconciliationGeneration), request.signal);
+                const uniqueCandidates = [...new Set(candidates)];
+                primeRawBatchReads(uniqueCandidates, commitment, (candidate) => minimumRawReadSequence.get(keyFor(definition, candidate)) ?? 0);
+                let validated;
+                try {
+                    const validationResults = await Promise.allSettled(uniqueCandidates.map((address) => validateIndexerCandidate(definition, address, providerFilters, commitment, request.signal)));
+                    const rejected = validationResults.find((result) => result.status === 'rejected');
+                    if (rejected !== undefined)
+                        throw rejected.reason;
+                    validated = validationResults.map((result) => result.value);
+                }
+                catch (cause) {
+                    if (request.signal?.aborted === true) {
+                        throw abortReason(request.signal);
+                    }
+                    if (isDisposed())
+                        throw new ContextDisposedError();
+                    if (cause instanceof IndexerCandidateConflictError) {
+                        throw new ProviderError('A configured indexer candidate conflicted with direct z.ink account state. Refresh the indexer or use targeted RPC discovery before retrying.', {
+                            accountType: definition.type,
+                            address: cause.address,
+                            cause,
+                            provider: indexer.identity,
+                            strategy: 'indexer',
+                        });
+                    }
+                    if (cause instanceof ProviderError) {
+                        throw new ProviderError(cause.message, {
+                            accountType: definition.type,
+                            ...(cause.address !== undefined
+                                ? { address: cause.address }
+                                : {}),
+                            cause,
+                            provider: cause.provider ?? provider.identity,
+                            strategy: 'indexer',
+                        });
+                    }
+                    /* v8 ignore next -- candidate reads and decoders normalize unknown failures before this defensive boundary. */
+                    if (!(cause instanceof SageSdkError)) {
+                        throw new ProviderError('The configured direct provider could not validate an indexer candidate. Check the direct provider connection and retry discovery.', {
+                            accountType: definition.type,
+                            provider: provider.identity,
+                            strategy: 'indexer',
+                        });
+                    }
+                    throw cause;
+                }
+                const snapshots = validated.filter((snapshot) => snapshot !== undefined);
+                if (request.policy !== 'no-store') {
+                    assertCacheCapacity(snapshots.map((snapshot) => keyFor(definition, snapshot.address)));
+                    for (const snapshot of snapshots) {
+                        storeSnapshot(keyFor(definition, snapshot.address), snapshot, operationInvalidationSequence);
+                    }
+                }
+                const slot = snapshots.reduce((earliest, snapshot) => earliest === undefined || snapshot.slot < earliest
+                    ? snapshot.slot
+                    : earliest, undefined);
+                return Object.freeze(attachReadMeta(snapshots, {
+                    commitment,
+                    filters: metadataFilters,
+                    indexer: Object.freeze({
+                        candidateCount: candidates.length,
+                        duplicateCount: candidates.length - uniqueCandidates.length,
+                        missingCount: uniqueCandidates.length - snapshots.length,
+                        validatedCount: snapshots.length,
+                    }),
+                    slot: slot ?? 0n,
+                    source: Object.freeze({ ...indexer.identity }),
+                    strategy: 'indexer',
+                }));
+            }
+            let accounts;
+            try {
+                const discoveryRead = sharedDiscovery(definition.programAddress, providerFilters, commitment, discoveryInvalidatedAt.get(definition.programAddress) ?? 0, reconciliationGeneration);
+                accounts = await waitForCaller(discoveryRead.promise, request.signal);
+            }
+            catch (cause) {
+                if (request.signal?.aborted === true) {
+                    throw abortReason(request.signal);
+                }
+                if (isDisposed()) {
+                    throw new ContextDisposedError();
+                }
+                if (cause instanceof SageSdkError) {
+                    throw cause;
+                }
+                throw new ProviderError('The configured provider could not discover the requested z.ink accounts. Check the discovery filters and provider connection, then retry.', { accountType: definition.type });
+            }
+            assertActive();
+            const snapshotsByAddress = new Map();
+            for (const account of accounts) {
+                assertProviderCommitment(account, commitment);
+                const snapshot = validateAndTimestamp(definition, copyRawAccount(account), provider.identity);
+                const existing = snapshotsByAddress.get(snapshot.address);
+                if (existing === undefined || isPreferredSnapshot(snapshot, existing)) {
+                    snapshotsByAddress.set(snapshot.address, snapshot);
+                }
+            }
+            const snapshots = [...snapshotsByAddress.values()];
+            if (request.policy !== 'no-store') {
+                assertCacheCapacity(snapshots.map((snapshot) => keyFor(definition, snapshot.address)));
+                for (const snapshot of snapshots) {
+                    storeSnapshot(keyFor(definition, snapshot.address), snapshot, operationInvalidationSequence);
+                }
+            }
+            const slot = snapshots.reduce((earliest, snapshot) => earliest === undefined || snapshot.slot < earliest
+                ? snapshot.slot
+                : earliest, undefined);
+            return Object.freeze(attachReadMeta(snapshots, {
+                commitment,
+                filters: metadataFilters,
+                slot: slot ?? 0n,
+                source: Object.freeze({ ...provider.identity }),
+                strategy: request.strategy === 'indexer'
+                    ? 'targeted-program-accounts'
+                    : request.strategy,
+            }));
+        },
+        async subscribe(definition, address, observer, options = {}) {
+            assertActive();
+            throwIfAborted(options.signal);
+            if (subscriptionProvider === undefined) {
+                throw new ProviderError('This SAGE context has no account subscription provider. Configure a WebSocket subscription provider before subscribing to live account updates.', { accountType: definition.type, address });
+            }
+            const commitment = requestedCommitment(options);
+            const key = keyFor(definition, address);
+            const registrationLifecycle = new AbortController();
+            let registration;
+            let resolveRegistration;
+            let rejectRegistration;
+            const registrationAttempt = new Promise((resolve, reject) => {
+                resolveRegistration = resolve;
+                rejectRegistration = reject;
+            });
+            let lastDelivered;
+            let stopPromise;
+            let resolveCompletion;
+            const completion = new Promise((resolve) => {
+                resolveCompletion = resolve;
+            });
+            trackSubscription(completion);
+            let resolveRegistrationDeliveryStarted;
+            const registrationDeliveryStarted = new Promise((resolve) => {
+                resolveRegistrationDeliveryStarted = resolve;
+            });
+            const subscriptionErrorMessage = 'The account subscription could not process a live z.ink update. Check the WebSocket provider and retry the subscription.';
+            const observerErrorMessage = 'The account subscription onSnapshot callback could not process a validated snapshot. Fix the consumer callback before retrying delivery.';
+            let notificationRunning = false;
+            let pendingSnapshot;
+            let pendingSnapshotAwaitingReconnect = false;
+            let reconnecting = false;
+            let reconnectPending = false;
+            let pendingReconnectReadSequence;
+            const pendingErrors = new Map();
+            const coalescedErrors = new Map();
+            let coalescedSnapshots = 0;
+            const emitDiagnostic = (event) => {
+                try {
+                    observer.onDiagnostic?.(event);
+                }
+                catch {
+                    // Diagnostics never interrupt delivery or transport cleanup.
+                }
+            };
+            const normalizeSubscriptionError = (cause, message) => cause instanceof SageSdkError
+                ? cause
+                : new ProviderError(message, {
+                    accountType: definition.type,
+                    address,
+                    cause,
+                });
+            const runNotifications = async () => {
+                if (notificationRunning)
+                    return;
+                notificationRunning = true;
+                try {
+                    while (!registrationLifecycle.signal.aborted && !isDisposed()) {
+                        const errorEntry = pendingErrors.entries().next().value;
+                        if (errorEntry !== undefined) {
+                            pendingErrors.delete(errorEntry[0]);
+                            coalescedErrors.delete(errorEntry[0]);
+                            try {
+                                const notification = observer.onError(errorEntry[1]);
+                                resolveRegistrationDeliveryStarted();
+                                await notification;
+                            }
+                            catch {
+                                resolveRegistrationDeliveryStarted();
+                                // Consumer observer failures never terminate transport.
+                            }
+                            continue;
+                        }
+                        const snapshot = pendingSnapshot;
+                        if (snapshot === undefined)
+                            return;
+                        if (pendingSnapshotAwaitingReconnect)
+                            return;
+                        pendingSnapshot = undefined;
+                        coalescedSnapshots = 0;
+                        try {
+                            const notification = observer.onSnapshot(snapshot);
+                            resolveRegistrationDeliveryStarted();
+                            await notification;
+                            lastDelivered = snapshot;
+                        }
+                        catch (cause) {
+                            resolveRegistrationDeliveryStarted();
+                            const error = normalizeSubscriptionError(cause, observerErrorMessage);
+                            pendingErrors.set(error.code, error);
+                        }
+                    }
+                }
+                finally {
+                    notificationRunning = false;
+                }
+            };
+            const reportError = (cause, message) => {
+                if (registrationLifecycle.signal.aborted)
+                    return;
+                const error = normalizeSubscriptionError(cause, message);
+                if (pendingErrors.has(error.code)) {
+                    const count = (coalescedErrors.get(error.code) ?? 0) + 1;
+                    coalescedErrors.set(error.code, count);
+                    emitDiagnostic({
+                        accountType: definition.type,
+                        address,
+                        coalescedCount: count,
+                        errorCode: error.code,
+                        kind: 'subscription-error-coalesced',
+                    });
+                }
+                pendingErrors.set(error.code, error);
+                void runNotifications();
+            };
+            const queueSnapshotCandidate = (selected, awaitReconnect = false) => {
+                const deliveryBaseline = pendingSnapshot ?? lastDelivered;
+                if (deliveryBaseline !== undefined &&
+                    !isPreferredSnapshot(selected, deliveryBaseline)) {
+                    return;
+                }
+                if (pendingSnapshot !== undefined) {
+                    coalescedSnapshots += 1;
+                    emitDiagnostic({
+                        accountType: definition.type,
+                        address,
+                        coalescedCount: coalescedSnapshots,
+                        kind: 'subscription-snapshot-coalesced',
+                    });
+                }
+                pendingSnapshot = selected;
+                pendingSnapshotAwaitingReconnect = awaitReconnect;
+                if (!awaitReconnect)
+                    void runNotifications();
+            };
+            const queueSelectedSnapshot = (fallback) => {
+                queueSnapshotCandidate(cachedSnapshot(key, commitment) ?? fallback);
+            };
+            const decodeAccountEvent = (event) => {
+                assertAccountSize(event.account);
+                const account = copyRawAccount(event.account);
+                if (account.address !== address) {
+                    throw new ProviderError(`The account subscription returned ${account.address} for requested address ${address}. Fix the WebSocket provider response before retrying.`, { accountType: definition.type, address });
+                }
+                assertProviderCommitment(account, commitment);
+                const snapshot = validateAndTimestamp(definition, account, subscriptionProvider.identity);
+                return snapshot;
+            };
+            const storeAndQueueSnapshot = (snapshot) => {
+                storeSubscriptionSnapshot(key, snapshot);
+                queueSelectedSnapshot(snapshot);
+            };
+            const processReconnect = (coalesce) => {
+                if (reconnecting) {
+                    reconnectPending = true;
+                    pendingReconnectReadSequence = Math.max(pendingReconnectReadSequence ?? 0, nextRawReadSequence);
+                    return;
+                }
+                reconnecting = true;
+                void (async () => {
+                    try {
+                        let useSettledReconnectRead = coalesce;
+                        do {
+                            const minimumReadSequence = pendingReconnectReadSequence;
+                            reconnectPending = false;
+                            pendingReconnectReadSequence = undefined;
+                            try {
+                                const snapshot = await waitForCaller(useSettledReconnectRead
+                                    ? sharedReconnectRead(definition, address, commitment)
+                                    : sharedDefinedRead(definition, address, commitment, true, minimumReadSequence), registrationLifecycle.signal);
+                                if (snapshot === undefined) {
+                                    throw new AccountNotFoundError(definition.type, address);
+                                }
+                                queueSelectedSnapshot(snapshot);
+                            }
+                            catch (cause) {
+                                reportError(cause, subscriptionErrorMessage);
+                            }
+                            useSettledReconnectRead = false;
+                        } while (reconnectPending &&
+                            !registrationLifecycle.signal.aborted &&
+                            !isDisposed());
+                    }
+                    finally {
+                        reconnecting = false;
+                        if (pendingSnapshotAwaitingReconnect &&
+                            pendingSnapshot !== undefined &&
+                            !registrationLifecycle.signal.aborted &&
+                            !isDisposed()) {
+                            const pending = pendingSnapshot;
+                            pendingSnapshotAwaitingReconnect = false;
+                            try {
+                                storeSubscriptionSnapshot(key, pending);
+                            }
+                            catch (cause) {
+                                pendingSnapshot = undefined;
+                                reportError(cause, subscriptionErrorMessage);
+                            }
+                        }
+                        void runNotifications();
+                    }
+                })();
+            };
+            const enqueue = (event) => {
+                if (registrationLifecycle.signal.aborted || isDisposed())
+                    return;
+                if (event.kind === 'reconnected') {
+                    processReconnect(true);
+                    return;
+                }
+                try {
+                    const snapshot = decodeAccountEvent(event);
+                    if (reconnecting) {
+                        const cached = cachedSnapshot(key, commitment);
+                        queueSnapshotCandidate(cached === undefined || isPreferredSnapshot(snapshot, cached)
+                            ? snapshot
+                            : cached, true);
+                        return;
+                    }
+                    storeAndQueueSnapshot(snapshot);
+                }
+                catch (cause) {
+                    reportError(cause, subscriptionErrorMessage);
+                }
+            };
+            const abortRegistration = () => registrationLifecycle.abort(options.signal?.aborted === true
+                ? options.signal.reason
+                : lifecycle.signal.reason);
+            options.signal?.addEventListener('abort', abortRegistration, {
+                once: true,
+            });
+            lifecycle.signal.addEventListener('abort', abortRegistration, {
+                once: true,
+            });
+            const cleanupRegistration = () => {
+                const unsubscribeRegistration = async (activeRegistration) => {
+                    try {
+                        await activeRegistration.unsubscribe();
+                    }
+                    catch {
+                        // Disposal remains best-effort when a transport is already gone.
+                    }
+                };
+                if (registration === undefined) {
+                    void registrationAttempt.then(async (activeRegistration) => {
+                        registration = activeRegistration;
+                        await unsubscribeRegistration(activeRegistration);
+                    }, () => undefined);
+                    return Promise.resolve();
+                }
+                return unsubscribeRegistration(registration);
+            };
+            const stop = () => {
+                if (stopPromise !== undefined)
+                    return stopPromise;
+                let resolveStop;
+                stopPromise = new Promise((resolve) => {
+                    resolveStop = resolve;
+                });
+                void (async () => {
+                    try {
+                        registrationLifecycle.abort();
+                        options.signal?.removeEventListener('abort', abortRegistration);
+                        lifecycle.signal.removeEventListener('abort', abortRegistration);
+                        await cleanupRegistration();
+                    }
+                    finally {
+                        resolveCompletion();
+                        resolveStop();
+                    }
+                })();
+                return stopPromise;
+            };
+            registrationLifecycle.signal.addEventListener('abort', () => void stop(), { once: true });
+            try {
+                try {
+                    const providerRegistration = subscriptionProvider.subscribeAccount({
+                        address,
+                        commitment,
+                        signal: registrationLifecycle.signal,
+                    }, (event) => void enqueue(event));
+                    void providerRegistration.then(resolveRegistration, rejectRegistration);
+                }
+                catch (cause) {
+                    rejectRegistration(cause);
+                }
+                registration = await waitForCaller(registrationAttempt, registrationLifecycle.signal);
+            }
+            catch (cause) {
+                const wasCancelled = registrationLifecycle.signal.aborted;
+                const cancellationReason = registrationLifecycle.signal.reason;
+                await stop();
+                if (wasCancelled) {
+                    throw cancellationReason;
+                }
+                if (cause instanceof SageSdkError)
+                    throw cause;
+                throw new ProviderError('The configured WebSocket provider could not register the requested account subscription. Check the provider connection and retry.', { accountType: definition.type, address });
+            }
+            processReconnect(false);
+            await waitForCaller(registrationDeliveryStarted, registrationLifecycle.signal);
+            return Object.freeze({ unsubscribe: stop });
+        },
+        async readRaw(address, options) {
+            assertActive();
+            throwIfAborted(options?.signal);
+            const account = await waitForCaller(sharedRawRead(address, requestedCommitment(options)), options?.signal);
+            return account === undefined ? undefined : copyRawAccount(account);
+        },
+    });
+}
+/** Creates an isolated context synchronously without performing network I/O.
+ *
+ * @example
+ * ```ts
+ * declare const rpc: SageRpc;
+ * const ctx = createSageContext({ cluster: 'zink-ptr', rpc });
+ * ```
+ */
+export function createSageContext(options) {
+    if (options.cluster !== 'zink-ptr' && options.game === undefined) {
+        throw new MissingGameContextError();
+    }
+    const game = options.game ?? ZINK_PTR_GAME_ADDRESS;
+    const defaultMaxAgeMs = configuredMaxAgeMs(options.defaultMaxAgeMs);
+    const maxAccountDataBytes = configuredLimit('maxAccountDataBytes', options.maxAccountDataBytes, DEFAULT_MAX_ACCOUNT_DATA_BYTES);
+    const maxCacheEntries = configuredLimit('maxCacheEntries', options.maxCacheEntries, DEFAULT_MAX_CACHE_ENTRIES);
+    const maxDiscoveryResults = configuredLimit('maxDiscoveryResults', options.maxDiscoveryResults, DEFAULT_MAX_DISCOVERY_RESULTS);
+    const maxReadManyAccounts = configuredLimit('maxReadManyAccounts', options.maxReadManyAccounts, DEFAULT_MAX_READ_MANY_ACCOUNTS);
+    let disposed = false;
+    const lifecycle = new AbortController();
+    const walletProfileDiscoveries = new Map();
+    lifecycle.signal.addEventListener('abort', () => walletProfileDiscoveries.clear(), { once: true });
+    const subscriptionCompletions = new Set();
+    const trackSubscription = (completion) => {
+        subscriptionCompletions.add(completion);
+        void completion.finally(() => subscriptionCompletions.delete(completion));
+    };
+    const provider = options.provider ??
+        createZinkProvider(options.rpc, clusterName(options.cluster), {
+            maxAccountDataBytes,
+            maxDiscoveryResults,
+        });
+    const data = createDataPort(options.cluster, provider, options.discovery?.indexer, options.subscriptions, options.commitment ?? DEFAULT_COMMITMENT, defaultMaxAgeMs, () => disposed, lifecycle, maxAccountDataBytes, maxCacheEntries, maxDiscoveryResults, maxReadManyAccounts, trackSubscription);
+    const context = {
+        cluster: options.cluster,
+        data,
+        game,
+        ...(options.registrySnapshotStore === undefined
+            ? {}
+            : { registrySnapshotStore: options.registrySnapshotStore }),
+        ...(options.writeRpc === undefined ? {} : { writeRpc: options.writeRpc }),
+        async dispose() {
+            if (!disposed) {
+                disposed = true;
+                markContextDisposed(context);
+                lifecycle.abort(new ContextDisposedError());
+                await Promise.all([...subscriptionCompletions]);
+            }
+        },
+    };
+    CONTEXT_DISCOVERY_RUNTIME.set(context, {
+        defaultCommitment: options.commitment ?? DEFAULT_COMMITMENT,
+        isDisposed: () => disposed,
+        lifecycle,
+        maxDiscoveryResults,
+        walletProfileDiscoveries,
+        ...(options.discovery?.walletProfiles === undefined
+            ? {}
+            : { walletProfiles: options.discovery.walletProfiles }),
+    });
+    return Object.freeze(context);
+}
+//# sourceMappingURL=context.js.map