@usearete/sdk 0.2.0 → 0.3.0

package/dist/index.esm.js

@@ -1,8 +1,9 @@
 import { inflate } from 'pako';
-import { Point } from '@noble/ed25519';
+import { Buffer } from 'buffer';
 
 const DEFAULT_MAX_ENTRIES_PER_VIEW = 10000;
 const DEFAULT_CONFIG = {
+    autoReconnect: true,
     reconnectIntervals: [1000, 2000, 4000, 8000, 16000],
     maxReconnectAttempts: 5,
     maxEntriesPerView: DEFAULT_MAX_ENTRIES_PER_VIEW,
@@ -67,51 +68,441 @@ function parseErrorCode(errorCode) {
 
 const GZIP_MAGIC_0 = 0x1f;
 const GZIP_MAGIC_1 = 0x8b;
+const FRAME_MODES = new Set(['state', 'append', 'list']);
+const LIVE_OPS = new Set(['upsert', 'patch', 'remove', 'delete']);
+const QUERY_FIELDS$1 = new Set([
+    'view',
+    'key',
+    'partition',
+    'filters',
+    'take',
+    'skip',
+    'after',
+    'snapshotLimit',
+]);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 function isGzipData(data) {
     return data.length >= 2 && data[0] === GZIP_MAGIC_0 && data[1] === GZIP_MAGIC_1;
 }
+function isSubscriptionId(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.trim() !== value)
+        return false;
+    if (/\p{Cc}/u.test(value))
+        return false;
+    return new TextEncoder().encode(value).byteLength <= 128;
+}
+function isMode(value) {
+    return typeof value === 'string' && FRAME_MODES.has(value);
+}
+function isSort(value) {
+    if (!isRecord(value))
+        return false;
+    return Array.isArray(value['field'])
+        && value['field'].every((entry) => typeof entry === 'string')
+        && (value['order'] === 'asc' || value['order'] === 'desc');
+}
+function isQuery(value) {
+    if (!isRecord(value) || typeof value['view'] !== 'string' || value['view'].length === 0) {
+        return false;
+    }
+    if (Object.keys(value).some((key) => !QUERY_FIELDS$1.has(key)))
+        return false;
+    if (value['key'] !== undefined && typeof value['key'] !== 'string')
+        return false;
+    if (value['partition'] !== undefined && typeof value['partition'] !== 'string')
+        return false;
+    if (value['filters'] !== undefined && !isRecord(value['filters']))
+        return false;
+    if (value['take'] !== undefined && (!Number.isInteger(value['take']) || Number(value['take']) <= 0)) {
+        return false;
+    }
+    if (value['skip'] !== undefined && (!Number.isInteger(value['skip']) || Number(value['skip']) < 0)) {
+        return false;
+    }
+    if (value['after'] !== undefined && typeof value['after'] !== 'string')
+        return false;
+    return value['snapshotLimit'] === undefined
+        || (Number.isInteger(value['snapshotLimit']) && Number(value['snapshotLimit']) > 0);
+}
+function hasV2Identity(value) {
+    return value['protocolVersion'] === 2 && isSubscriptionId(value['subscriptionId']);
+}
 function isSnapshotFrame(frame) {
-    return frame.op === 'snapshot';
+    return 'op' in frame && frame.op === 'snapshot';
 }
 function isSubscribedFrame(frame) {
-    return frame.op === 'subscribed';
+    return 'op' in frame && frame.op === 'subscribed';
+}
+function isUnsubscribedFrame(frame) {
+    return 'op' in frame && frame.op === 'unsubscribed';
+}
+function isErrorFrame(frame) {
+    return 'type' in frame && frame.type === 'error';
 }
 function isEntityFrame(frame) {
-    return ['create', 'upsert', 'patch', 'delete'].includes(frame.op);
+    return 'op' in frame && LIVE_OPS.has(frame.op);
 }
-function parseFrame(data) {
-    if (typeof data === 'string') {
+function decodeFrame(data) {
+    if (typeof data === 'string')
         return JSON.parse(data);
-    }
     const bytes = new Uint8Array(data);
-    if (isGzipData(bytes)) {
-        const decompressed = inflate(bytes);
-        const jsonString = new TextDecoder().decode(decompressed);
-        return JSON.parse(jsonString);
+    const decoded = isGzipData(bytes) ? inflate(bytes) : bytes;
+    return JSON.parse(new TextDecoder('utf-8').decode(decoded));
+}
+function parseFrame(data) {
+    const frame = decodeFrame(data);
+    if (!isValidFrame(frame)) {
+        throw new Error('Invalid WebSocket protocol v2 frame');
     }
-    const jsonString = new TextDecoder('utf-8').decode(data);
-    return JSON.parse(jsonString);
+    return frame;
 }
 async function parseFrameFromBlob(blob) {
-    const arrayBuffer = await blob.arrayBuffer();
-    return parseFrame(arrayBuffer);
+    return parseFrame(await blob.arrayBuffer());
 }
 function isValidFrame(frame) {
-    if (typeof frame !== 'object' || frame === null) {
+    if (!isRecord(frame) || frame['protocolVersion'] !== 2)
+        return false;
+    if (frame['type'] === 'error') {
+        return (frame['subscriptionId'] === null || isSubscriptionId(frame['subscriptionId']))
+            && typeof frame['code'] === 'string'
+            && typeof frame['fatal'] === 'boolean'
+            && (frame['message'] === undefined || typeof frame['message'] === 'string')
+            && (frame['error'] === undefined || typeof frame['error'] === 'string')
+            && (frame['retryable'] === undefined || typeof frame['retryable'] === 'boolean');
+    }
+    if (!hasV2Identity(frame) || typeof frame['op'] !== 'string')
         return false;
+    if (frame['op'] === 'unsubscribed')
+        return true;
+    if (frame['op'] === 'subscribed') {
+        return isQuery(frame['query'])
+            && isMode(frame['mode'])
+            && (frame['sort'] === undefined || isSort(frame['sort']));
     }
-    const f = frame;
-    if (typeof f['entity'] !== 'string' ||
-        typeof f['op'] !== 'string' ||
-        typeof f['mode'] !== 'string' ||
-        !['state', 'append', 'list'].includes(f['mode'])) {
+    if (!isMode(frame['mode']) || typeof frame['entity'] !== 'string')
         return false;
+    if (frame['op'] === 'snapshot') {
+        return typeof frame['snapshotId'] === 'string'
+            && frame['snapshotId'].length > 0
+            && typeof frame['authoritative'] === 'boolean'
+            && typeof frame['complete'] === 'boolean'
+            && (frame['key'] === undefined || typeof frame['key'] === 'string')
+            && Array.isArray(frame['data'])
+            && frame['data'].every((entry) => isRecord(entry) && typeof entry['key'] === 'string' && 'data' in entry);
+    }
+    return LIVE_OPS.has(frame['op'])
+        && typeof frame['key'] === 'string'
+        && 'data' in frame
+        && (frame['seq'] === undefined || typeof frame['seq'] === 'string')
+        && (frame['append'] === undefined
+            || (Array.isArray(frame['append'])
+                && frame['append'].every((entry) => typeof entry === 'string')));
+}
+
+let fallbackId = 0;
+const QUERY_FIELDS = new Set([
+    'view',
+    'key',
+    'partition',
+    'filters',
+    'take',
+    'skip',
+    'after',
+    'snapshotLimit',
+]);
+const SUBSCRIPTION_FIELDS = new Set([
+    'type',
+    'protocolVersion',
+    'subscriptionId',
+    'query',
+    'snapshot',
+]);
+function canonicalJsonValue(value, path) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => canonicalJsonValue(entry, `${path}[${index}]`));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalJsonValue(entry, `${path}.${key}`)]));
     }
-    if (f['op'] === 'snapshot') {
-        return Array.isArray(f['data']);
+    throw new TypeError(`${path} must contain JSON values`);
+}
+function assertPositiveInteger(value, field) {
+    if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+        throw new TypeError(`${field} must be a positive integer`);
+    }
+}
+function validateSubscriptionId(subscriptionId) {
+    if (subscriptionId.length === 0 || subscriptionId.trim() !== subscriptionId) {
+        throw new TypeError('subscriptionId must be non-empty with no surrounding whitespace');
+    }
+    if (/\p{Cc}/u.test(subscriptionId)) {
+        throw new TypeError('subscriptionId must not contain control characters');
+    }
+    if (new TextEncoder().encode(subscriptionId).byteLength > 128) {
+        throw new TypeError('subscriptionId must not exceed 128 bytes');
+    }
+}
+function createSubscriptionId() {
+    const randomUuid = globalThis.crypto?.randomUUID?.();
+    if (randomUuid)
+        return `a4-${randomUuid}`;
+    fallbackId++;
+    return `a4-${Date.now().toString(36)}-${fallbackId.toString(36)}`;
+}
+function normalizeSubscriptionQuery(query) {
+    if (typeof query.view !== 'string' || query.view.length === 0) {
+        throw new TypeError('query.view must be a non-empty string');
+    }
+    if (Object.keys(query).some((key) => !QUERY_FIELDS.has(key))) {
+        throw new TypeError('query contains an unknown protocol v2 field');
+    }
+    if (query.key !== undefined && typeof query.key !== 'string') {
+        throw new TypeError('query.key must be a string');
+    }
+    if (query.partition !== undefined && typeof query.partition !== 'string') {
+        throw new TypeError('query.partition must be a string');
+    }
+    if (query.filters !== undefined
+        && (query.filters === null || typeof query.filters !== 'object' || Array.isArray(query.filters))) {
+        throw new TypeError('query.filters must be an object');
+    }
+    if (query.after !== undefined && typeof query.after !== 'string') {
+        throw new TypeError('query.after must be a string');
+    }
+    assertPositiveInteger(query.take, 'query.take');
+    assertPositiveInteger(query.snapshotLimit, 'query.snapshotLimit');
+    if (query.skip !== undefined && (!Number.isInteger(query.skip) || query.skip < 0)) {
+        throw new TypeError('query.skip must be a non-negative integer');
+    }
+    const normalized = { view: query.view };
+    if (query.key !== undefined)
+        normalized.key = query.key;
+    if (query.partition !== undefined)
+        normalized.partition = query.partition;
+    if (query.filters !== undefined) {
+        normalized.filters = Object.fromEntries(Object.entries(query.filters)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([path, value]) => [path, canonicalJsonValue(value, `query.filters.${path}`)]));
+    }
+    if (query.take !== undefined)
+        normalized.take = query.take;
+    if (query.skip !== undefined)
+        normalized.skip = query.skip;
+    if (query.after !== undefined)
+        normalized.after = query.after;
+    if (query.snapshotLimit !== undefined)
+        normalized.snapshotLimit = query.snapshotLimit;
+    return normalized;
+}
+function normalizeSubscriptionRequest(request) {
+    const enabled = request.snapshot?.enabled ?? true;
+    if (typeof enabled !== 'boolean') {
+        throw new TypeError('snapshot.enabled must be a boolean');
+    }
+    return {
+        query: normalizeSubscriptionQuery(request.query),
+        snapshot: { enabled },
+    };
+}
+function canonicalQueryKey(request) {
+    const normalized = normalizeSubscriptionRequest(request);
+    return JSON.stringify({ query: normalized.query, snapshot: normalized.snapshot });
+}
+function normalizeSubscription(subscription) {
+    if (subscription.type !== 'subscribe' || subscription.protocolVersion !== 2) {
+        throw new TypeError('Subscription must use WebSocket protocolVersion 2');
+    }
+    if (Object.keys(subscription).some((key) => !SUBSCRIPTION_FIELDS.has(key))) {
+        throw new TypeError('Subscription contains an unknown protocol v2 field');
+    }
+    validateSubscriptionId(subscription.subscriptionId);
+    const request = normalizeSubscriptionRequest(subscription);
+    return {
+        type: 'subscribe',
+        protocolVersion: 2,
+        subscriptionId: subscription.subscriptionId,
+        query: request.query,
+        snapshot: request.snapshot,
+    };
+}
+function refreshError(value) {
+    if (value instanceof AreteError)
+        return value;
+    return new AreteError(value instanceof Error ? value.message : 'Subscription refresh failed', 'SUBSCRIPTION_ERROR', value);
+}
+class SubscriptionRegistry {
+    constructor(connection, queryStore) {
+        this.connection = connection;
+        this.queryStore = queryStore;
+        this.subscriptions = new Map();
+        this.subscriptionsById = new Map();
+    }
+    subscribe(query, snapshotEnabled = true) {
+        const request = normalizeSubscriptionRequest({
+            query,
+            snapshot: { enabled: snapshotEnabled },
+        });
+        const queryKey = canonicalQueryKey(request);
+        let tracker = this.subscriptions.get(queryKey);
+        if (tracker) {
+            tracker.refCount++;
+        }
+        else {
+            const subscription = {
+                type: 'subscribe',
+                protocolVersion: 2,
+                subscriptionId: createSubscriptionId(),
+                query: request.query,
+                snapshot: request.snapshot,
+            };
+            tracker = { subscription, queryKey, refCount: 1 };
+            this.queryStore.register(subscription, queryKey);
+            try {
+                this.connection.subscribe(subscription);
+            }
+            catch (error) {
+                this.queryStore.unregister(subscription.subscriptionId);
+                throw error;
+            }
+            this.subscriptions.set(queryKey, tracker);
+            this.subscriptionsById.set(subscription.subscriptionId, tracker);
+        }
+        return this.createLease(tracker);
+    }
+    refresh(query, snapshotEnabled = true) {
+        const tracker = this.getTracker(query, snapshotEnabled);
+        if (!tracker) {
+            return Promise.reject(new AreteError(`Cannot refresh inactive query '${query.view}'`, 'SUBSCRIPTION_NOT_FOUND'));
+        }
+        return this.refreshTracker(tracker);
+    }
+    /**
+     * Refresh every active subscription for a view, optionally narrowed to one
+     * serialized key. Resolves immediately when nothing matches — refreshing a
+     * view with no active subscriptions is a no-op, not an error.
+     */
+    refreshView(view, key) {
+        const matches = Array.from(this.subscriptions.values()).filter(({ subscription }) => subscription.query.view === view
+            && (key === undefined || subscription.query.key === key));
+        return Promise.all(matches.map((tracker) => this.refreshTracker(tracker))).then(() => undefined);
+    }
+    getRefCount(query, snapshotEnabled = true) {
+        return this.getTracker(query, snapshotEnabled)?.refCount ?? 0;
+    }
+    getActiveSubscriptions() {
+        return Array.from(this.subscriptions.values(), ({ subscription }) => normalizeSubscription(subscription));
+    }
+    getSnapshot(query, snapshotEnabled = true) {
+        const tracker = this.getTracker(query, snapshotEnabled);
+        return tracker
+            ? this.queryStore.getSnapshot(tracker.subscription.subscriptionId)
+            : undefined;
+    }
+    handleConnectionState(state) {
+        if (state === 'reconnecting')
+            this.queryStore.beginReconnect();
+        if (state === 'error') {
+            this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        }
+    }
+    clear() {
+        for (const { subscription } of this.subscriptions.values()) {
+            try {
+                this.connection.unsubscribe(subscription.subscriptionId);
+            }
+            catch {
+                // Local release must complete even when the socket can no longer send.
+            }
+            finally {
+                this.queryStore.unregister(subscription.subscriptionId);
+            }
+        }
+        this.subscriptions.clear();
+        this.subscriptionsById.clear();
+    }
+    createLease(tracker) {
+        let released = false;
+        const subscriptionId = tracker.subscription.subscriptionId;
+        return {
+            subscription: tracker.subscription,
+            queryKey: tracker.queryKey,
+            getSnapshot: () => {
+                const snapshot = this.queryStore.getSnapshot(subscriptionId);
+                if (!snapshot) {
+                    throw new AreteError('Query lease has been released', 'SUBSCRIPTION_NOT_FOUND');
+                }
+                return snapshot;
+            },
+            onChange: (callback) => this.queryStore.onChange(subscriptionId, callback),
+            onUpdate: (callback) => this.queryStore.onUpdate(subscriptionId, callback),
+            onRichUpdate: (callback) => this.queryStore.onRichUpdate(subscriptionId, callback),
+            refresh: () => this.refreshTracker(tracker),
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.releaseTracker(tracker);
+            },
+        };
+    }
+    getTracker(query, snapshotEnabled) {
+        return this.subscriptions.get(canonicalQueryKey({
+            query,
+            snapshot: { enabled: snapshotEnabled },
+        }));
+    }
+    refreshTracker(tracker) {
+        if (this.subscriptionsById.get(tracker.subscription.subscriptionId) !== tracker) {
+            return Promise.reject(new AreteError('Cannot refresh a released query lease', 'SUBSCRIPTION_NOT_FOUND'));
+        }
+        if (tracker.refreshPromise)
+            return tracker.refreshPromise;
+        const subscriptionId = tracker.subscription.subscriptionId;
+        const waitForSnapshot = tracker.subscription.snapshot.enabled;
+        const completion = this.queryStore.beginRefresh(subscriptionId, waitForSnapshot);
+        try {
+            this.connection.refresh(tracker.subscription);
+        }
+        catch (value) {
+            const error = refreshError(value);
+            this.queryStore.failRefresh(subscriptionId, error);
+            return waitForSnapshot ? completion : Promise.reject(error);
+        }
+        const promise = completion;
+        tracker.refreshPromise = promise;
+        const clear = () => {
+            if (tracker.refreshPromise === promise)
+                tracker.refreshPromise = undefined;
+        };
+        void promise.then(clear, clear);
+        return promise;
+    }
+    releaseTracker(tracker) {
+        if (this.subscriptionsById.get(tracker.subscription.subscriptionId) !== tracker)
+            return;
+        tracker.refCount--;
+        if (tracker.refCount > 0)
+            return;
+        this.subscriptions.delete(tracker.queryKey);
+        this.subscriptionsById.delete(tracker.subscription.subscriptionId);
+        try {
+            this.connection.unsubscribe(tracker.subscription.subscriptionId);
+        }
+        catch {
+            // ConnectionManager already removed local membership before sending.
+        }
+        finally {
+            this.queryStore.unregister(tracker.subscription.subscriptionId);
+        }
     }
-    return (typeof f['key'] === 'string' &&
-        ['create', 'upsert', 'patch', 'delete'].includes(f['op']));
 }
 
 const TOKEN_REFRESH_BUFFER_SECONDS = 60;
@@ -173,14 +564,15 @@ function isSocketIssueMessage(value) {
     }
     const candidate = value;
     return candidate['type'] === 'error'
-        && typeof candidate['message'] === 'string'
         && typeof candidate['code'] === 'string'
-        && typeof candidate['retryable'] === 'boolean'
-        && typeof candidate['fatal'] === 'boolean';
+        && typeof candidate['fatal'] === 'boolean'
+        && (candidate['message'] === undefined || typeof candidate['message'] === 'string')
+        && (candidate['error'] === undefined || typeof candidate['error'] === 'string')
+        && (candidate['retryable'] === undefined || typeof candidate['retryable'] === 'boolean');
 }
-function isHostedAreteWebsocketUrl(websocketUrl) {
+function isHostedAreteEndpoint(url) {
     try {
-        return new URL(websocketUrl).hostname.toLowerCase().endsWith(HOSTED_WEBSOCKET_SUFFIX);
+        return new URL(url).hostname.toLowerCase().endsWith(HOSTED_WEBSOCKET_SUFFIX);
     }
     catch {
         return false;
@@ -199,24 +591,32 @@ class ConnectionManager {
         this.pingInterval = null;
         this.tokenRefreshTimeout = null;
         this.tokenRefreshInFlight = null;
+        this.tokenRequestInFlight = null;
         this.currentState = 'disconnected';
-        this.subscriptionQueue = [];
-        this.activeSubscriptions = new Set();
+        this.subscriptionQueue = new Map();
+        this.activeSubscriptions = new Map();
+        this.socketGeneration = 0;
+        this.pendingConnect = null;
         this.frameHandlers = new Set();
         this.stateHandlers = new Set();
         this.socketIssueHandlers = new Set();
+        this.tokenScopes = new Set();
+        this.requestedScopes = new Set();
         this.reconnectForTokenRefresh = false;
         const websocketUrl = config.websocketUrl && config.websocketUrl !== DISABLED_WEBSOCKET_URL
             ? config.websocketUrl
             : null;
         this.websocketUrl = websocketUrl;
-        this.hostedAreteUrl = websocketUrl !== null && isHostedAreteWebsocketUrl(websocketUrl);
+        this.hostedAreteUrl = websocketUrl !== null && isHostedAreteEndpoint(websocketUrl);
+        this.autoReconnect = config.autoReconnect ?? DEFAULT_CONFIG.autoReconnect;
         this.reconnectIntervals = config.reconnectIntervals ?? DEFAULT_CONFIG.reconnectIntervals;
         this.maxReconnectAttempts =
             config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
         this.authConfig = config.auth;
         if (config.initialSubscriptions) {
-            this.subscriptionQueue.push(...config.initialSubscriptions);
+            for (const subscription of config.initialSubscriptions) {
+                this.addQueuedSubscription(subscription);
+            }
         }
     }
     getTokenEndpoint() {
@@ -246,7 +646,7 @@ class ConnectionManager {
         const strategy = this.getAuthStrategy();
         return strategy.kind === 'token-provider' || strategy.kind === 'token-endpoint';
     }
-    updateTokenState(result) {
+    updateTokenState(result, requestedScopes) {
         const normalized = normalizeTokenResult(result);
         if (!normalized.token) {
             throw new AreteError('Authentication provider returned an empty token', 'TOKEN_INVALID');
@@ -254,6 +654,7 @@ class ConnectionManager {
         this.currentToken = normalized.token;
         this.tokenExpiry = normalizeExpiryTimestamp(normalized.expiresAt, normalized.expires_at)
             ?? parseJwtExpiry(normalized.token);
+        this.tokenScopes = new Set(normalized.scopes ?? requestedScopes);
         if (this.isTokenExpired()) {
             throw new AreteError('Authentication token is expired', 'TOKEN_EXPIRED');
         }
@@ -262,23 +663,65 @@ class ConnectionManager {
     clearTokenState() {
         this.currentToken = undefined;
         this.tokenExpiry = undefined;
+        this.tokenScopes.clear();
+    }
+    tokenCovers(scopes) {
+        return scopes.every((scope) => this.tokenScopes.has(scope));
     }
-    async getOrRefreshToken(forceRefresh = false) {
-        if (!forceRefresh && this.currentToken && !this.isTokenExpired()) {
+    async getOrRefreshToken(forceRefresh = false, requiredScopes = ['read']) {
+        for (const scope of requiredScopes)
+            this.requestedScopes.add(scope);
+        if (!forceRefresh && this.currentToken && !this.isTokenExpired() && this.tokenCovers(requiredScopes)) {
             return this.currentToken;
         }
+        if (this.tokenRequestInFlight) {
+            await this.tokenRequestInFlight;
+            if (!this.currentToken) {
+                return undefined;
+            }
+            if (this.currentToken && !this.isTokenExpired() && this.tokenCovers(requiredScopes)) {
+                return this.currentToken;
+            }
+            throw new AreteError(`Authentication token was not granted required scopes: ${requiredScopes.join(', ')}`, 'AUTH_REQUIRED');
+        }
+        let request;
+        request = Promise.resolve().then(() => this.fetchAuthToken([...new Set([...this.tokenScopes, ...this.requestedScopes])], () => this.tokenRequestInFlight === request));
+        this.tokenRequestInFlight = request;
+        try {
+            const token = await request;
+            if (token && !this.tokenCovers(requiredScopes)) {
+                throw new AreteError(`Authentication token was not granted required scopes: ${requiredScopes.join(', ')}`, 'AUTH_REQUIRED');
+            }
+            return token;
+        }
+        finally {
+            if (this.tokenRequestInFlight === request) {
+                this.tokenRequestInFlight = null;
+            }
+        }
+    }
+    async fetchAuthToken(scopes, isCurrent) {
         const strategy = this.getAuthStrategy();
+        const requireCurrent = () => {
+            if (!isCurrent()) {
+                throw new AreteError('Authentication request was superseded', 'CONNECTION_CANCELLED');
+            }
+        };
         // For hosted Arete URLs, auth is required - fail early with clear message
         if (strategy.kind === 'none' && this.hostedAreteUrl) {
             throw new AreteError('Arete authentication required. Please provide auth.publishableKey to AreteProvider. ' +
                 'Get your key from https://arete.run/dashboard', 'AUTH_REQUIRED');
         }
         switch (strategy.kind) {
-            case 'static-token':
-                return this.updateTokenState(strategy.token);
+            case 'static-token': {
+                requireCurrent();
+                return this.updateTokenState(strategy.token, scopes);
+            }
             case 'token-provider':
                 try {
-                    return this.updateTokenState(await strategy.getToken());
+                    const result = await strategy.getToken({ scopes });
+                    requireCurrent();
+                    return this.updateTokenState(result, scopes);
                 }
                 catch (error) {
                     if (error instanceof AreteError) {
@@ -288,7 +731,9 @@ class ConnectionManager {
                 }
             case 'token-endpoint':
                 try {
-                    return this.updateTokenState(await this.fetchTokenFromEndpoint(strategy.endpoint));
+                    const result = await this.fetchTokenFromEndpoint(strategy.endpoint, scopes);
+                    requireCurrent();
+                    return this.updateTokenState(result, scopes);
                 }
                 catch (error) {
                     if (error instanceof AreteError) {
@@ -297,15 +742,17 @@ class ConnectionManager {
                     throw new AreteError('Failed to fetch authentication token from endpoint', 'AUTH_REQUIRED', error);
                 }
             case 'none':
+                requireCurrent();
                 return undefined;
         }
     }
-    createTokenEndpointRequestBody() {
+    createTokenEndpointRequestBody(scopes) {
         return {
             websocket_url: this.websocketUrl ?? '',
+            scopes,
         };
     }
-    async fetchTokenFromEndpoint(tokenEndpoint) {
+    async fetchTokenFromEndpoint(tokenEndpoint, scopes = [...this.requestedScopes]) {
         const response = await fetch(tokenEndpoint, {
             method: 'POST',
             headers: {
@@ -316,7 +763,7 @@ class ConnectionManager {
                 'Content-Type': 'application/json',
             },
             credentials: this.authConfig?.tokenEndpointCredentials,
-            body: JSON.stringify(this.createTokenEndpointRequestBody()),
+            body: JSON.stringify(this.createTokenEndpointRequestBody(scopes)),
         });
         if (!response.ok) {
             const rawError = await response.text();
@@ -381,10 +828,11 @@ class ConnectionManager {
         if (this.tokenRefreshInFlight) {
             return this.tokenRefreshInFlight;
         }
-        this.tokenRefreshInFlight = (async () => {
+        let refresh;
+        refresh = (async () => {
             const previousToken = this.currentToken;
             try {
-                await this.getOrRefreshToken(true);
+                await this.getOrRefreshToken(true, [...this.tokenScopes]);
                 if (previousToken &&
                     this.currentToken &&
                     this.currentToken !== previousToken &&
@@ -396,16 +844,23 @@ class ConnectionManager {
                         this.rotateConnectionForTokenRefresh();
                     }
                 }
-                this.scheduleTokenRefresh();
+                if (this.tokenRefreshInFlight === refresh) {
+                    this.scheduleTokenRefresh();
+                }
             }
             catch {
-                this.scheduleTokenRefresh();
+                if (this.tokenRefreshInFlight === refresh) {
+                    this.scheduleTokenRefresh();
+                }
             }
             finally {
-                this.tokenRefreshInFlight = null;
+                if (this.tokenRefreshInFlight === refresh) {
+                    this.tokenRefreshInFlight = null;
+                }
             }
         })();
-        return this.tokenRefreshInFlight;
+        this.tokenRefreshInFlight = refresh;
+        return refresh;
     }
     async sendInBandAuthRefresh(token) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -451,6 +906,11 @@ class ConnectionManager {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.reconnectForTokenRefresh) {
             return;
         }
+        if (!this.autoReconnect) {
+            this.updateState('error', 'Token refresh requires a new connection, but automatic reconnection is disabled');
+            this.ws.close(1000, 'token refresh');
+            return;
+        }
         this.reconnectForTokenRefresh = true;
         this.updateState('reconnecting');
         this.ws.close(1000, 'token refresh');
@@ -490,8 +950,14 @@ class ConnectionManager {
     getState() {
         return this.currentState;
     }
-    async getHttpAuthToken(forceRefresh = false) {
-        return this.getOrRefreshToken(forceRefresh);
+    async getHttpAuthToken(requiredScopesOrForce = ['read'], forceRefresh = false) {
+        const requiredScopes = typeof requiredScopesOrForce === 'boolean'
+            ? ['read']
+            : requiredScopesOrForce;
+        const force = typeof requiredScopesOrForce === 'boolean'
+            ? requiredScopesOrForce
+            : forceRefresh;
+        return this.getOrRefreshToken(force, requiredScopes);
     }
     clearHttpAuthToken() {
         this.clearTokenState();
@@ -516,49 +982,75 @@ class ConnectionManager {
     }
     notifySocketIssue(message) {
         const issue = {
-            error: message.error,
-            message: message.message,
+            error: message.error ?? message.code,
+            message: message.message ?? message.error ?? message.code,
             code: parseErrorCode(message.code),
-            retryable: message.retryable,
+            retryable: message.retryable ?? false,
             retryAfter: message.retry_after,
             suggestedAction: message.suggested_action,
             docsUrl: message.docs_url,
             fatal: message.fatal,
+            subscriptionId: message.subscriptionId,
         };
         for (const handler of this.socketIssueHandlers) {
             handler(issue);
         }
         return issue;
     }
-    async connect() {
+    async connect(recovering = false) {
         this.requireWebsocketUrl();
         if (this.ws?.readyState === WebSocket.OPEN ||
             this.ws?.readyState === WebSocket.CONNECTING ||
             this.currentState === 'connecting') {
             return;
         }
-        this.updateState('connecting');
+        const generation = ++this.socketGeneration;
+        const cancellation = new Promise((_resolve, reject) => {
+            this.pendingConnect = { generation, reject };
+        });
+        this.updateState(recovering ? 'reconnecting' : 'connecting');
+        if (generation !== this.socketGeneration) {
+            return cancellation;
+        }
         let token;
         try {
-            token = await this.getOrRefreshToken();
+            token = await Promise.race([
+                this.getOrRefreshToken(false, ['read']),
+                cancellation,
+            ]);
         }
         catch (error) {
-            this.updateState('error', error instanceof Error ? error.message : 'Failed to get token');
+            if (this.pendingConnect?.generation === generation) {
+                this.pendingConnect = null;
+            }
+            if (generation === this.socketGeneration) {
+                this.updateState(recovering ? 'reconnecting' : 'error', error instanceof Error ? error.message : 'Failed to get token');
+            }
             throw error;
         }
+        if (generation !== this.socketGeneration) {
+            throw new AreteError('WebSocket connection attempt was superseded', 'CONNECTION_CANCELLED');
+        }
         const wsUrl = this.buildAuthUrl(token);
-        return new Promise((resolve, reject) => {
+        const socketConnection = new Promise((resolve, reject) => {
             let settled = false;
             const finish = (fn) => {
                 if (settled) {
                     return;
                 }
                 settled = true;
+                if (this.pendingConnect?.generation === generation) {
+                    this.pendingConnect = null;
+                }
                 fn();
             };
             try {
-                this.ws = this.createWebSocket(wsUrl, token);
-                this.ws.onopen = () => {
+                const socket = this.createWebSocket(wsUrl, token);
+                this.ws = socket;
+                const isCurrentSocket = () => this.ws === socket && this.socketGeneration === generation;
+                socket.onopen = () => {
+                    if (!isCurrentSocket())
+                        return;
                     this.reconnectAttempts = 0;
                     this.updateState('connected');
                     this.startPingInterval();
@@ -567,7 +1059,9 @@ class ConnectionManager {
                     this.flushSubscriptionQueue();
                     finish(() => resolve());
                 };
-                this.ws.onmessage = async (event) => {
+                socket.onmessage = async (event) => {
+                    if (!isCurrentSocket())
+                        return;
                     try {
                         let frame;
                         if (event.data instanceof ArrayBuffer) {
@@ -583,7 +1077,17 @@ class ConnectionManager {
                                 return;
                             }
                             if (isSocketIssueMessage(parsed)) {
-                                this.handleSocketIssueMessage(parsed);
+                                if (parsed.protocolVersion === 2) {
+                                    const issueFrame = parseFrame(JSON.stringify(parsed));
+                                    if (isCurrentSocket())
+                                        this.notifyFrameHandlers(issueFrame);
+                                    if (parsed.subscriptionId === null || parsed.fatal) {
+                                        this.handleSocketIssueMessage(parsed);
+                                    }
+                                }
+                                else {
+                                    this.handleSocketIssueMessage(parsed);
+                                }
                                 return;
                             }
                             frame = parseFrame(JSON.stringify(parsed));
@@ -591,21 +1095,28 @@ class ConnectionManager {
                         else {
                             throw new AreteError(`Unsupported message type: ${typeof event.data}`, 'PARSE_ERROR');
                         }
-                        this.notifyFrameHandlers(frame);
+                        if (isCurrentSocket())
+                            this.notifyFrameHandlers(frame);
                     }
                     catch {
+                        if (!isCurrentSocket())
+                            return;
                         this.updateState('error', 'Failed to parse frame from server');
                     }
                 };
-                this.ws.onerror = () => {
+                socket.onerror = () => {
+                    if (!isCurrentSocket())
+                        return;
                     const error = new AreteError('WebSocket connection error', 'CONNECTION_ERROR');
                     const wasConnecting = this.currentState === 'connecting';
-                    this.updateState('error', error.message);
+                    this.updateState(wasConnecting || !this.autoReconnect ? 'error' : 'reconnecting', error.message);
                     if (wasConnecting) {
                         finish(() => reject(error));
                     }
                 };
-                this.ws.onclose = (event) => {
+                socket.onclose = (event) => {
+                    if (!isCurrentSocket())
+                        return;
                     this.stopPingInterval();
                     this.clearTokenRefreshTimeout();
                     this.ws = null;
@@ -614,13 +1125,17 @@ class ConnectionManager {
                             ? `${event.code}: ${event.reason}`
                             : `code ${event.code}`;
                         const errorMessage = `WebSocket closed before open (${detail})`;
-                        this.updateState('error', errorMessage);
+                        this.updateState(recovering ? 'reconnecting' : 'error', errorMessage);
                         finish(() => reject(new AreteError(errorMessage, 'CONNECTION_ERROR')));
                         return;
                     }
                     if (this.reconnectForTokenRefresh) {
                         this.reconnectForTokenRefresh = false;
-                        void this.connect().catch(() => {
+                        if (!this.autoReconnect) {
+                            this.updateState('error', 'WebSocket closed for token refresh and automatic reconnection is disabled');
+                            return;
+                        }
+                        void this.connect(true).catch(() => {
                             this.handleReconnect();
                         });
                         return;
@@ -636,8 +1151,12 @@ class ConnectionManager {
                             : /expired|invalid|token/i.test(closeReason);
                         if (isAuthError) {
                             this.clearTokenState();
+                            if (!this.autoReconnect) {
+                                this.updateState('error', `Authentication refresh requires reconnection, but automatic reconnection is disabled: ${closeReason || event.code}`);
+                                return;
+                            }
                             // Try to reconnect immediately with a fresh token
-                            void this.connect().catch(() => {
+                            void this.connect(true).catch(() => {
                                 this.handleReconnect();
                             });
                             return;
@@ -653,85 +1172,142 @@ class ConnectionManager {
                         }
                     }
                     if (this.currentState !== 'disconnected') {
-                        this.handleReconnect();
+                        if (this.autoReconnect) {
+                            this.handleReconnect();
+                        }
+                        else {
+                            const detail = event.reason
+                                ? `${event.code}: ${event.reason}`
+                                : `code ${event.code}`;
+                            this.updateState('error', `WebSocket closed (${detail}) and automatic reconnection is disabled`);
+                        }
                     }
                 };
             }
             catch (error) {
                 const hsError = new AreteError('Failed to create WebSocket connection', 'CONNECTION_ERROR', error);
-                this.updateState('error', hsError.message);
-                reject(hsError);
+                this.updateState(recovering ? 'reconnecting' : 'error', hsError.message);
+                finish(() => reject(hsError));
             }
         });
+        return Promise.race([socketConnection, cancellation]);
     }
     disconnect() {
         this.clearReconnectTimeout();
         this.stopPingInterval();
         this.clearTokenRefreshTimeout();
         this.reconnectForTokenRefresh = false;
-        this.updateState('disconnected');
+        const pendingConnect = this.pendingConnect;
+        this.pendingConnect = null;
+        this.tokenRequestInFlight = null;
+        this.tokenRefreshInFlight = null;
+        this.socketGeneration++;
+        pendingConnect?.reject(new AreteError('WebSocket connection attempt was cancelled', 'CONNECTION_CANCELLED'));
         if (this.ws) {
-            this.ws.close();
+            const socket = this.ws;
             this.ws = null;
+            socket.close();
         }
+        this.updateState('disconnected');
     }
     subscribe(subscription) {
         this.requireWebsocketUrl();
-        const subKey = this.makeSubKey(subscription);
+        const normalized = normalizeSubscription(subscription);
+        const subscriptionId = normalized.subscriptionId;
+        const existing = this.activeSubscriptions.get(subscriptionId)
+            ?? this.subscriptionQueue.get(subscriptionId);
+        if (existing) {
+            if (JSON.stringify(existing) !== JSON.stringify(normalized)) {
+                throw new AreteError(`subscriptionId '${subscriptionId}' is already registered locally`, 'DUPLICATE_SUBSCRIPTION_ID');
+            }
+            return;
+        }
         if (this.currentState === 'connected' && this.ws?.readyState === WebSocket.OPEN) {
-            if (this.activeSubscriptions.has(subKey)) {
-                return;
+            try {
+                this.ws.send(JSON.stringify(normalized));
             }
-            const subMsg = { type: 'subscribe', ...subscription };
-            this.ws.send(JSON.stringify(subMsg));
-            this.activeSubscriptions.add(subKey);
+            catch (error) {
+                try {
+                    const unsubMsg = {
+                        type: 'unsubscribe',
+                        protocolVersion: 2,
+                        subscriptionId,
+                    };
+                    this.ws.send(JSON.stringify(unsubMsg));
+                }
+                catch {
+                    // The original send error is more useful; cleanup is best-effort.
+                }
+                throw error;
+            }
+            this.activeSubscriptions.set(subscriptionId, normalized);
         }
         else {
-            const alreadyQueued = this.subscriptionQueue.some((queuedSubscription) => this.makeSubKey(queuedSubscription) === subKey);
-            if (!alreadyQueued) {
-                this.subscriptionQueue.push(subscription);
-            }
+            this.subscriptionQueue.set(subscriptionId, normalized);
         }
     }
-    unsubscribe(view, key) {
-        const subscription = { view, key };
-        const subKey = this.makeSubKey(subscription);
-        if (this.activeSubscriptions.has(subKey)) {
-            this.activeSubscriptions.delete(subKey);
+    unsubscribe(subscriptionId) {
+        this.subscriptionQueue.delete(subscriptionId);
+        if (this.activeSubscriptions.has(subscriptionId)) {
+            this.activeSubscriptions.delete(subscriptionId);
             if (this.ws?.readyState === WebSocket.OPEN) {
-                const unsubMsg = { type: 'unsubscribe', view, key };
+                const unsubMsg = { type: 'unsubscribe', protocolVersion: 2, subscriptionId };
                 this.ws.send(JSON.stringify(unsubMsg));
             }
         }
     }
+    refresh(subscription) {
+        this.requireWebsocketUrl();
+        const normalized = normalizeSubscription(subscription);
+        const subscriptionId = normalized.subscriptionId;
+        const existing = this.activeSubscriptions.get(subscriptionId)
+            ?? this.subscriptionQueue.get(subscriptionId);
+        if (!existing) {
+            throw new AreteError(`Cannot refresh inactive subscription '${subscriptionId}'`, 'SUBSCRIPTION_NOT_FOUND');
+        }
+        if (JSON.stringify(existing) !== JSON.stringify(normalized)) {
+            throw new AreteError('Cannot change a subscription while refreshing it', 'INVALID_SUBSCRIPTION');
+        }
+        try {
+            this.unsubscribe(subscriptionId);
+            this.subscribe(existing);
+        }
+        catch (error) {
+            if (!this.activeSubscriptions.has(subscriptionId)
+                && !this.subscriptionQueue.has(subscriptionId)) {
+                this.addQueuedSubscription(existing);
+            }
+            throw error;
+        }
+    }
     isConnected() {
         return this.currentState === 'connected' && this.ws?.readyState === WebSocket.OPEN;
     }
-    makeSubKey(subscription) {
-        return `${subscription.view}:${subscription.key ?? '*'}:${subscription.partition ?? ''}`;
-    }
     flushSubscriptionQueue() {
-        while (this.subscriptionQueue.length > 0) {
-            const subscription = this.subscriptionQueue.shift();
-            if (subscription) {
-                this.subscribe(subscription);
-            }
+        const queuedSubscriptions = Array.from(this.subscriptionQueue.values());
+        this.subscriptionQueue.clear();
+        for (const subscription of queuedSubscriptions) {
+            this.subscribe(subscription);
         }
     }
     resubscribeActive() {
-        for (const subKey of this.activeSubscriptions) {
-            const [view, key, partition] = subKey.split(':');
-            const subscription = {
-                view: view ?? '',
-                key: key === '*' ? undefined : key,
-                partition: partition || undefined,
-            };
+        for (const subscription of this.activeSubscriptions.values()) {
             if (this.ws?.readyState === WebSocket.OPEN) {
-                const subMsg = { type: 'subscribe', ...subscription };
-                this.ws.send(JSON.stringify(subMsg));
+                this.ws.send(JSON.stringify(subscription));
             }
         }
     }
+    addQueuedSubscription(subscription) {
+        const normalized = normalizeSubscription(subscription);
+        const subscriptionId = normalized.subscriptionId;
+        const existing = this.subscriptionQueue.get(subscriptionId);
+        if (existing && JSON.stringify(existing) !== JSON.stringify(normalized)) {
+            throw new AreteError(`subscriptionId '${subscriptionId}' is already queued`, 'DUPLICATE_SUBSCRIPTION_ID');
+        }
+        if (!existing) {
+            this.subscriptionQueue.set(subscriptionId, normalized);
+        }
+    }
     updateState(state, error) {
         this.currentState = state;
         for (const handler of this.stateHandlers) {
@@ -744,6 +1320,10 @@ class ConnectionManager {
         }
     }
     handleReconnect() {
+        if (!this.autoReconnect) {
+            this.updateState('error', 'Automatic reconnection is disabled');
+            return;
+        }
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             this.updateState('error', `Max reconnection attempts (${this.reconnectAttempts}) reached`);
             return;
@@ -753,8 +1333,12 @@ class ConnectionManager {
         const delay = this.reconnectIntervals[attemptIndex] ?? 1000;
         this.reconnectAttempts++;
         this.reconnectTimeout = setTimeout(() => {
-            this.connect().catch(() => {
-                /* retry handled by onclose */
+            this.connect(true).catch(() => {
+                // Once a socket exists, its close event owns the next retry. Token
+                // acquisition and socket construction can fail before that point.
+                if (this.ws === null && this.currentState !== 'disconnected') {
+                    this.handleReconnect();
+                }
             });
         }, delay);
     }
@@ -781,6 +1365,14 @@ class ConnectionManager {
 }
 
 const INTERNAL_SEQ_FIELD = '__seq';
+class ProcessedSlotTimeoutError extends Error {
+    constructor(targetSlot, processedSlot) {
+        super(`Timed out waiting for Arete to process slot ${targetSlot}`);
+        this.name = 'ProcessedSlotTimeoutError';
+        this.targetSlot = targetSlot;
+        this.processedSlot = processedSlot;
+    }
+}
 function isObject(item) {
     return item !== null && typeof item === 'object' && !Array.isArray(item);
 }
@@ -848,6 +1440,8 @@ class FrameProcessor {
         this.pendingUpdates = [];
         this.flushTimer = null;
         this.isProcessing = false;
+        this.latestProcessedSlot = null;
+        this.processedSlotWaiters = new Set();
         this.storage = storage;
         this.maxEntriesPerView = config.maxEntriesPerView === undefined
             ? DEFAULT_MAX_ENTRIES_PER_VIEW
@@ -855,6 +1449,9 @@ class FrameProcessor {
         this.flushIntervalMs = config.flushIntervalMs ?? 0;
         this.schemas = config.schemas;
         this.patchSchemas = config.patchSchemas;
+        this.queryStore = config.queryStore;
+        this.warnOnValidationError = config.warnOnValidationError ?? true;
+        this.onValidationError = config.onValidationError;
     }
     getSchema(viewPath, patch = false) {
         const schemas = patch ? this.patchSchemas : this.schemas;
@@ -866,20 +1463,44 @@ class FrameProcessor {
         const entityKey = entityName;
         return schemas[entityKey] ?? null;
     }
-    normalizeEntity(viewPath, data, patch = false) {
-        const schema = this.getSchema(viewPath, patch)
-            ?? (!patch ? null : this.getSchema(viewPath));
-        if (!schema)
+    normalizeEntity(viewPath, data, context, patch = false) {
+        const fullSchema = this.getSchema(viewPath);
+        const patchSchema = this.getSchema(viewPath, true);
+        const schemas = patch
+            ? [patchSchema, fullSchema]
+            : [fullSchema, patchSchema];
+        let validationError;
+        for (const schema of schemas) {
+            if (!schema)
+                continue;
+            try {
+                const result = schema.safeParse(data);
+                if (result.success) {
+                    return stripUndefinedProperties(result.data);
+                }
+                validationError = result.error;
+            }
+            catch (error) {
+                validationError = error;
+            }
+        }
+        if (!fullSchema && !patchSchema)
             return data;
-        const result = schema.safeParse(data);
-        if (!result.success) {
-            console.warn('[Arete] Frame validation failed:', {
-                view: viewPath,
-                error: result.error,
-            });
-            return null;
+        const diagnostic = {
+            view: viewPath,
+            ...context,
+            error: validationError,
+        };
+        try {
+            this.onValidationError?.(diagnostic);
+        }
+        catch (callbackError) {
+            console.error('[Arete] Frame validation callback failed:', callbackError);
         }
-        return stripUndefinedProperties(result.data);
+        if (this.warnOnValidationError) {
+            console.warn('[Arete] Frame validation failed:', diagnostic);
+        }
+        return null;
     }
     hasSchema(viewPath) {
         return this.getSchema(viewPath) !== null;
@@ -935,8 +1556,19 @@ class FrameProcessor {
         const seq = data[INTERNAL_SEQ_FIELD];
         return typeof seq === 'string' ? seq : undefined;
     }
-    attachInternalSeq(viewPath, data, seq) {
-        if (!seq || !this.hasSchema(viewPath) || !isObject(data)) {
+    compareSeq(left, right) {
+        const [leftSlot, leftIndex = ''] = left.split(':', 2);
+        const [rightSlot, rightIndex = ''] = right.split(':', 2);
+        if (/^\d+$/.test(leftSlot ?? '') && /^\d+$/.test(rightSlot ?? '')) {
+            const leftValue = BigInt(leftSlot);
+            const rightValue = BigInt(rightSlot);
+            if (leftValue !== rightValue)
+                return leftValue < rightValue ? -1 : 1;
+        }
+        return leftIndex.localeCompare(rightIndex);
+    }
+    attachInternalSeq(_viewPath, data, seq) {
+        if (!seq || !isObject(data)) {
             return data;
         }
         Object.defineProperty(data, INTERNAL_SEQ_FIELD, {
@@ -966,6 +1598,45 @@ class FrameProcessor {
         }
         this.flushPendingUpdates();
     }
+    getProcessedSlot() {
+        return this.latestProcessedSlot;
+    }
+    waitForProcessedSlot(slot, options = {}) {
+        const targetSlot = this.normalizeSlot(slot);
+        if (this.latestProcessedSlot !== null && this.latestProcessedSlot >= targetSlot) {
+            return Promise.resolve(this.latestProcessedSlot);
+        }
+        if (options.signal?.aborted) {
+            return Promise.reject(this.createAbortError());
+        }
+        if (options.timeoutMs !== undefined
+            && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+            return Promise.reject(new RangeError('timeoutMs must be a non-negative finite number'));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                targetSlot,
+                resolve,
+                reject,
+                timeout: null,
+                signal: options.signal,
+            };
+            const rejectWaiter = (error) => {
+                this.removeProcessedSlotWaiter(waiter);
+                reject(error);
+            };
+            if (options.timeoutMs !== undefined) {
+                waiter.timeout = setTimeout(() => {
+                    rejectWaiter(new ProcessedSlotTimeoutError(targetSlot, this.latestProcessedSlot));
+                }, options.timeoutMs);
+            }
+            if (options.signal) {
+                waiter.onAbort = () => rejectWaiter(this.createAbortError());
+                options.signal.addEventListener('abort', waiter.onAbort, { once: true });
+            }
+            this.processedSlotWaiters.add(waiter);
+        });
+    }
     /**
      * Clean up any pending timers. Call when disposing the processor.
      */
@@ -992,31 +1663,115 @@ class FrameProcessor {
         this.isProcessing = true;
         const batch = this.pendingUpdates;
         this.pendingUpdates = [];
-        const viewsToEnforce = new Set();
-        for (const { frame } of batch) {
-            const viewPath = this.processFrameWithoutEnforce(frame);
-            if (viewPath) {
-                viewsToEnforce.add(viewPath);
+        try {
+            const viewsToEnforce = new Set();
+            for (const { frame } of batch) {
+                const viewPath = this.processFrameWithoutEnforce(frame);
+                if (viewPath) {
+                    viewsToEnforce.add(viewPath);
+                }
+            }
+            viewsToEnforce.forEach((viewPath) => {
+                this.enforceMaxEntries(viewPath);
+            });
+            for (const { frame } of batch) {
+                this.markFrameProcessed(frame);
             }
         }
-        viewsToEnforce.forEach((viewPath) => {
-            this.enforceMaxEntries(viewPath);
-        });
-        this.isProcessing = false;
+        finally {
+            this.isProcessing = false;
+        }
     }
     processFrame(frame) {
-        if (isSubscribedFrame(frame)) {
+        if (isErrorFrame(frame)) {
+            this.queryStore?.failFrame(frame);
+        }
+        else if (isUnsubscribedFrame(frame)) ;
+        else if (isSubscribedFrame(frame)) {
             this.handleSubscribedFrame(frame);
         }
         else if (isSnapshotFrame(frame)) {
             this.handleSnapshotFrame(frame);
         }
-        else {
+        else if (isEntityFrame(frame)) {
             this.handleEntityFrame(frame);
         }
+        this.markFrameProcessed(frame);
+    }
+    normalizeSlot(slot) {
+        if (typeof slot === 'number') {
+            if (!Number.isSafeInteger(slot) || slot < 0) {
+                throw new RangeError('slot must be a non-negative safe integer or bigint');
+            }
+            return BigInt(slot);
+        }
+        if (slot < 0n) {
+            throw new RangeError('slot must be non-negative');
+        }
+        return slot;
+    }
+    slotFromSeq(seq) {
+        if (typeof seq !== 'string') {
+            return null;
+        }
+        const slot = seq.split(':', 1)[0];
+        return slot && /^\d+$/.test(slot) ? BigInt(slot) : null;
+    }
+    frameSlot(frame) {
+        if (isSubscribedFrame(frame) || isUnsubscribedFrame(frame) || isErrorFrame(frame)) {
+            return null;
+        }
+        if (isSnapshotFrame(frame)) {
+            let latest = null;
+            for (const entity of frame.data) {
+                const slot = isObject(entity.data)
+                    ? this.slotFromSeq(entity.data._seq)
+                    : null;
+                if (slot !== null && (latest === null || slot > latest)) {
+                    latest = slot;
+                }
+            }
+            return latest;
+        }
+        return this.slotFromSeq(frame.seq)
+            ?? (isObject(frame.data) ? this.slotFromSeq(frame.data._seq) : null);
+    }
+    markFrameProcessed(frame) {
+        const slot = this.frameSlot(frame);
+        if (slot === null || (this.latestProcessedSlot !== null && slot <= this.latestProcessedSlot)) {
+            return;
+        }
+        this.latestProcessedSlot = slot;
+        for (const waiter of [...this.processedSlotWaiters]) {
+            if (slot >= waiter.targetSlot) {
+                this.removeProcessedSlotWaiter(waiter);
+                waiter.resolve(slot);
+            }
+        }
+    }
+    removeProcessedSlotWaiter(waiter) {
+        this.processedSlotWaiters.delete(waiter);
+        if (waiter.timeout !== null) {
+            clearTimeout(waiter.timeout);
+        }
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+    }
+    createAbortError() {
+        const error = new Error('Waiting for processed slot was aborted');
+        error.name = 'AbortError';
+        return error;
     }
     processFrameWithoutEnforce(frame) {
-        if (isSubscribedFrame(frame)) {
+        if (isErrorFrame(frame)) {
+            this.queryStore?.failFrame(frame);
+            return null;
+        }
+        else if (isUnsubscribedFrame(frame)) {
+            return null;
+        }
+        else if (isSubscribedFrame(frame)) {
             this.handleSubscribedFrame(frame);
             return null;
         }
@@ -1024,17 +1779,20 @@ class FrameProcessor {
             this.handleSnapshotFrameWithoutEnforce(frame);
             return frame.entity;
         }
-        else {
+        else if (isEntityFrame(frame)) {
             this.handleEntityFrameWithoutEnforce(frame);
             return frame.entity;
         }
+        return null;
     }
     handleSubscribedFrame(frame) {
+        const viewPath = frame.query.view;
         if (this.storage.setViewConfig && frame.sort) {
-            this.storage.setViewConfig(frame.view, {
-                sort: this.normalizeSortConfig(frame.view, frame.sort),
+            this.storage.setViewConfig(viewPath, {
+                sort: this.normalizeSortConfig(viewPath, frame.sort),
             });
         }
+        this.queryStore?.acknowledge(frame.subscriptionId, frame.query, frame.mode, frame.sort ? this.normalizeSortConfig(viewPath, frame.sort) : undefined);
     }
     handleSnapshotFrame(frame) {
         this.handleSnapshotFrameWithoutEnforce(frame);
@@ -1042,12 +1800,18 @@ class FrameProcessor {
     }
     handleSnapshotFrameWithoutEnforce(frame) {
         const viewPath = frame.entity;
+        const acceptedKeys = [];
         for (const entity of frame.data) {
-            const normalized = this.normalizeEntity(viewPath, entity.data);
+            const normalized = this.normalizeEntity(viewPath, entity.data, {
+                key: entity.key,
+                operation: 'snapshot',
+                seq: this.extractSeq(entity.data),
+            });
             if (normalized === null) {
                 continue;
             }
             const nextValue = this.attachInternalSeq(viewPath, normalized, this.extractSeq(entity.data));
+            acceptedKeys.push(entity.key);
             const previousValue = this.storage.get(viewPath, entity.key);
             this.storage.set(viewPath, entity.key, nextValue);
             this.storage.notifyUpdate(viewPath, entity.key, {
@@ -1057,6 +1821,7 @@ class FrameProcessor {
             });
             this.emitRichUpdate(viewPath, entity.key, previousValue, nextValue, 'upsert');
         }
+        this.queryStore?.stageSnapshot(frame, acceptedKeys);
     }
     handleEntityFrame(frame) {
         this.handleEntityFrameWithoutEnforce(frame);
@@ -1065,44 +1830,86 @@ class FrameProcessor {
     handleEntityFrameWithoutEnforce(frame) {
         const viewPath = frame.entity;
         const previousValue = this.storage.get(viewPath, frame.key);
+        const previousSequence = this.getInternalSeq(previousValue);
+        const duplicateOrStaleSequence = frame.seq !== undefined
+            && previousSequence !== undefined
+            && this.compareSeq(frame.seq, previousSequence) <= 0;
         switch (frame.op) {
-            case 'create':
             case 'upsert':
                 {
-                    const normalized = this.normalizeEntity(viewPath, frame.data);
+                    if (frame.data === null)
+                        break;
+                    if (duplicateOrStaleSequence && previousValue !== null) {
+                        const update = {
+                            type: 'upsert',
+                            key: frame.key,
+                            data: previousValue,
+                        };
+                        this.queryStore?.applyLive(frame.subscriptionId, frame.key, update, this.createRichUpdate(frame.key, null, previousValue), frame.seq);
+                        break;
+                    }
+                    const normalized = this.normalizeEntity(viewPath, frame.data, {
+                        key: frame.key,
+                        operation: 'upsert',
+                        seq: frame.seq ?? this.extractSeq(frame.data),
+                    });
                     if (normalized === null) {
                         break;
                     }
                     const nextValue = this.attachInternalSeq(viewPath, normalized, frame.seq ?? this.extractSeq(frame.data));
                     this.storage.set(viewPath, frame.key, nextValue);
-                    this.storage.notifyUpdate(viewPath, frame.key, {
+                    const update = {
                         type: 'upsert',
                         key: frame.key,
                         data: nextValue,
-                    });
-                    this.emitRichUpdate(viewPath, frame.key, previousValue, nextValue, frame.op);
+                    };
+                    this.storage.notifyUpdate(viewPath, frame.key, update);
+                    const richUpdate = this.createRichUpdate(frame.key, previousValue, nextValue);
+                    this.storage.notifyRichUpdate(viewPath, frame.key, richUpdate);
+                    this.queryStore?.applyLive(frame.subscriptionId, frame.key, update, richUpdate, frame.seq ?? this.extractSeq(frame.data));
                     break;
                 }
             case 'patch': {
+                if (frame.data === null)
+                    break;
                 const existing = this.storage.get(viewPath, frame.key);
-                const normalizedPatch = this.normalizeEntity(viewPath, frame.data, true);
+                const normalizedPatch = this.normalizeEntity(viewPath, frame.data, {
+                    key: frame.key,
+                    operation: 'patch',
+                    seq: frame.seq ?? this.extractSeq(frame.data),
+                }, true);
                 if (normalizedPatch === null) {
                     break;
                 }
+                if (duplicateOrStaleSequence && existing !== null) {
+                    const update = {
+                        type: 'patch',
+                        key: frame.key,
+                        data: normalizedPatch,
+                    };
+                    this.queryStore?.applyLive(frame.subscriptionId, frame.key, update, this.createRichUpdate(frame.key, existing, existing, normalizedPatch), frame.seq);
+                    break;
+                }
                 const appendPaths = this.normalizeAppendPaths(viewPath, frame.append);
                 const merged = existing
                     ? deepMergeWithAppend(existing, normalizedPatch, appendPaths)
                     : normalizedPatch;
                 const nextValue = this.attachInternalSeq(viewPath, merged, frame.seq ?? this.extractSeq(frame.data) ?? this.getInternalSeq(existing));
                 this.storage.set(viewPath, frame.key, nextValue);
-                this.storage.notifyUpdate(viewPath, frame.key, {
+                const update = {
                     type: 'patch',
                     key: frame.key,
                     data: normalizedPatch,
-                });
-                this.emitRichUpdate(viewPath, frame.key, previousValue, nextValue, 'patch', normalizedPatch);
+                };
+                this.storage.notifyUpdate(viewPath, frame.key, update);
+                const richUpdate = this.createRichUpdate(frame.key, previousValue, nextValue, normalizedPatch);
+                this.storage.notifyRichUpdate(viewPath, frame.key, richUpdate);
+                this.queryStore?.applyLive(frame.subscriptionId, frame.key, update, richUpdate, frame.seq ?? this.extractSeq(frame.data));
                 break;
             }
+            case 'remove':
+                this.queryStore?.applyLive(frame.subscriptionId, frame.key, { type: 'remove', key: frame.key });
+                break;
             case 'delete':
                 this.storage.delete(viewPath, frame.key);
                 this.storage.notifyUpdate(viewPath, frame.key, {
@@ -1113,6 +1920,7 @@ class FrameProcessor {
                     const richUpdate = { type: 'deleted', key: frame.key, lastKnown: previousValue };
                     this.storage.notifyRichUpdate(viewPath, frame.key, richUpdate);
                 }
+                this.queryStore?.deleteGlobal(viewPath, frame.key, previousValue ?? undefined);
                 break;
         }
     }
@@ -1122,13 +1930,20 @@ class FrameProcessor {
             : { type: 'updated', key, before, after, patch };
         this.storage.notifyRichUpdate(viewPath, key, richUpdate);
     }
+    createRichUpdate(key, before, after, patch) {
+        return before === null
+            ? { type: 'created', key, data: after }
+            : { type: 'updated', key, before, after, patch };
+    }
     enforceMaxEntries(viewPath) {
         if (this.maxEntriesPerView === null)
             return;
         if (!this.storage.evictOldest)
             return;
         while (this.storage.size(viewPath) > this.maxEntriesPerView) {
-            this.storage.evictOldest(viewPath);
+            const evicted = this.storage.evictOldest(viewPath);
+            if (evicted !== undefined)
+                this.queryStore?.evict(viewPath, evicted);
         }
     }
 }
@@ -1275,7 +2090,7 @@ class MemoryAdapter {
     }
 }
 
-function getNestedValue(obj, path) {
+function getNestedValue$1(obj, path) {
     let current = obj;
     for (const segment of path) {
         if (current === null || current === undefined)
@@ -1431,7 +2246,7 @@ class SortedStorageDecorator {
         sortedKeys.splice(insertIdx, 0, key);
     }
     binarySearchInsertPosition(viewPath, sortedKeys, sortConfig, newKey, newValue) {
-        const newSortValue = getNestedValue(newValue, sortConfig.field);
+        const newSortValue = getNestedValue$1(newValue, sortConfig.field);
         const isDesc = sortConfig.order === 'desc';
         let low = 0;
         let high = sortedKeys.length;
@@ -1439,7 +2254,7 @@ class SortedStorageDecorator {
             const mid = Math.floor((low + high) / 2);
             const midKey = sortedKeys[mid];
             const midEntity = this.inner.get(viewPath, midKey);
-            const midValue = getNestedValue(midEntity, sortConfig.field);
+            const midValue = getNestedValue$1(midEntity, sortConfig.field);
             let cmp = compareSortValues(newSortValue, midValue);
             if (isDesc)
                 cmp = -cmp;
@@ -1462,8 +2277,8 @@ class SortedStorageDecorator {
         const isDesc = sortConfig.order === 'desc';
         const entries = allKeys.map(k => [k, this.inner.get(viewPath, k)]);
         entries.sort((a, b) => {
-            const aValue = getNestedValue(a[1], sortConfig.field);
-            const bValue = getNestedValue(b[1], sortConfig.field);
+            const aValue = getNestedValue$1(a[1], sortConfig.field);
+            const bValue = getNestedValue$1(b[1], sortConfig.field);
             let cmp = compareSortValues(aValue, bValue);
             if (isDesc)
                 cmp = -cmp;
@@ -1476,303 +2291,584 @@ class SortedStorageDecorator {
     }
 }
 
-class SubscriptionRegistry {
-    constructor(connection) {
-        this.subscriptions = new Map();
-        this.connection = connection;
+function getNestedValue(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
     }
-    subscribe(subscription) {
-        const subKey = this.makeSubKey(subscription);
-        const existing = this.subscriptions.get(subKey);
-        if (existing) {
-            existing.refCount++;
+    return current;
+}
+function compareValues(left, right) {
+    if (left === right)
+        return 0;
+    if (left === undefined || left === null)
+        return -1;
+    if (right === undefined || right === null)
+        return 1;
+    if (typeof left === 'number' && typeof right === 'number')
+        return left - right;
+    if (typeof left === 'bigint' && typeof right === 'bigint')
+        return left < right ? -1 : 1;
+    if (typeof left === 'boolean' && typeof right === 'boolean') {
+        return Number(left) - Number(right);
+    }
+    return String(left).localeCompare(String(right));
+}
+function compareSequences(left, right) {
+    if (typeof left !== 'string' || typeof right !== 'string')
+        return compareValues(left, right);
+    const [leftSlot, leftIndex = ''] = left.split(':', 2);
+    const [rightSlot, rightIndex = ''] = right.split(':', 2);
+    if (/^\d+$/.test(leftSlot ?? '') && /^\d+$/.test(rightSlot ?? '')) {
+        const leftValue = BigInt(leftSlot);
+        const rightValue = BigInt(rightSlot);
+        if (leftValue !== rightValue)
+            return leftValue < rightValue ? -1 : 1;
+    }
+    return leftIndex.localeCompare(rightIndex);
+}
+function appendUnique(target, keys) {
+    for (const key of keys) {
+        if (!target.includes(key))
+            target.push(key);
+    }
+}
+class QueryStore {
+    constructor(storage) {
+        this.storage = storage;
+        this.records = new Map();
+    }
+    register(subscription, queryKey) {
+        if (this.records.has(subscription.subscriptionId))
+            return;
+        this.records.set(subscription.subscriptionId, {
+            subscription,
+            queryKey,
+            keys: [],
+            sequences: new Map(),
+            isLoading: subscription.snapshot.enabled,
+            isRefreshing: false,
+            resolved: !subscription.snapshot.enabled,
+            listeners: new Set(),
+            updateListeners: new Set(),
+            richUpdateListeners: new Set(),
+            version: 0,
+            cachedVersion: -1,
+        });
+    }
+    unregister(subscriptionId) {
+        const record = this.records.get(subscriptionId);
+        if (!record)
+            return;
+        this.rejectRefresh(record, new AreteError('Subscription was released while refreshing', 'SUBSCRIPTION_NOT_FOUND'));
+        this.records.delete(subscriptionId);
+    }
+    getSubscription(subscriptionId) {
+        return this.records.get(subscriptionId)?.subscription;
+    }
+    getQueryKey(subscriptionId) {
+        return this.records.get(subscriptionId)?.queryKey;
+    }
+    getSnapshot(subscriptionId) {
+        const record = this.records.get(subscriptionId);
+        if (!record)
+            return undefined;
+        if (record.cachedSnapshot && record.cachedVersion === record.version) {
+            return record.cachedSnapshot;
         }
-        else {
-            this.subscriptions.set(subKey, {
-                subscription,
-                refCount: 1,
-            });
-            this.connection.subscribe(subscription);
+        const data = record.keys.flatMap((key) => {
+            const entity = this.storage.get(record.subscription.query.view, key);
+            return entity === null ? [] : [entity];
+        });
+        const snapshot = {
+            subscriptionId,
+            query: record.subscription.query,
+            keys: record.keys,
+            data,
+            isLoading: record.isLoading,
+            isRefreshing: record.isRefreshing,
+            ...(record.error ? { error: record.error } : {}),
+        };
+        record.cachedSnapshot = snapshot;
+        record.cachedVersion = record.version;
+        return snapshot;
+    }
+    onChange(subscriptionId, callback) {
+        const listeners = this.requireRecord(subscriptionId).listeners;
+        listeners.add(callback);
+        return () => listeners.delete(callback);
+    }
+    onUpdate(subscriptionId, callback) {
+        const listeners = this.requireRecord(subscriptionId).updateListeners;
+        listeners.add(callback);
+        return () => listeners.delete(callback);
+    }
+    onRichUpdate(subscriptionId, callback) {
+        const listeners = this.requireRecord(subscriptionId).richUpdateListeners;
+        listeners.add(callback);
+        return () => listeners.delete(callback);
+    }
+    acknowledge(subscriptionId, effectiveQuery, mode, sort) {
+        const record = this.records.get(subscriptionId);
+        if (!record)
+            return;
+        record.mode = mode;
+        record.sort = sort;
+        record.error = undefined;
+        if (!record.subscription.snapshot.enabled) {
+            record.isLoading = false;
+            record.isRefreshing = false;
+            record.resolved = true;
+        }
+        if (effectiveQuery.view !== record.subscription.query.view) {
+            this.fail(subscriptionId, new AreteError('Server acknowledged a different view for the subscription', 'INVALID_FRAME'));
+            return;
         }
-        return () => this.unsubscribe(subscription);
+        this.touch(record);
     }
-    unsubscribe(subscription) {
-        const subKey = this.makeSubKey(subscription);
-        const existing = this.subscriptions.get(subKey);
-        if (existing) {
-            existing.refCount--;
-            if (existing.refCount <= 0) {
-                this.subscriptions.delete(subKey);
-                this.connection.unsubscribe(subscription.view, subscription.key);
+    stageSnapshot(frame, keys) {
+        const record = this.records.get(frame.subscriptionId);
+        if (!record)
+            return;
+        if (!record.staged
+            || record.staged.snapshotId !== frame.snapshotId) {
+            record.staged = {
+                snapshotId: frame.snapshotId,
+                authoritative: frame.authoritative,
+                keys: [],
+            };
+        }
+        const staged = record.staged;
+        if (staged.authoritative !== frame.authoritative) {
+            this.fail(frame.subscriptionId, new AreteError('Snapshot batches disagree on authoritative mode', 'INVALID_FRAME'));
+            record.staged = undefined;
+            return;
+        }
+        appendUnique(staged.keys, keys);
+        if (!frame.complete)
+            return;
+        const stagedKeys = staged.keys;
+        if (frame.authoritative) {
+            const retained = new Set(stagedKeys);
+            for (const key of record.sequences.keys()) {
+                if (!retained.has(key))
+                    record.sequences.delete(key);
+            }
+        }
+        for (const key of stagedKeys) {
+            const sequence = this.entitySequence(record.subscription.query.view, key);
+            if (sequence !== undefined)
+                record.sequences.set(key, sequence);
+        }
+        record.keys = frame.authoritative
+            ? [...stagedKeys]
+            : this.mergeIncremental(record.keys, stagedKeys);
+        record.staged = undefined;
+        record.isLoading = false;
+        record.isRefreshing = false;
+        record.resolved = true;
+        record.error = undefined;
+        this.touch(record);
+        this.resolveRefresh(record);
+        for (const key of stagedKeys) {
+            const data = this.storage.get(record.subscription.query.view, key);
+            if (data !== null) {
+                this.emitUpdate(record, { type: 'upsert', key, data });
+                this.emitRichUpdate(record, { type: 'created', key, data });
             }
         }
     }
-    getRefCount(subscription) {
-        const subKey = this.makeSubKey(subscription);
-        return this.subscriptions.get(subKey)?.refCount ?? 0;
+    applyLive(subscriptionId, key, update, richUpdate, sequence) {
+        const record = this.records.get(subscriptionId);
+        if (!record)
+            return;
+        if (update.type === 'remove') {
+            const lastKnown = this.storage.get(record.subscription.query.view, key) ?? undefined;
+            record.keys = record.keys.filter((entry) => entry !== key);
+            record.sequences.delete(key);
+            this.touch(record);
+            this.emitUpdate(record, update);
+            this.emitRichUpdate(record, { type: 'removed', key, lastKnown });
+            return;
+        }
+        if (!record.keys.includes(key))
+            record.keys = [...record.keys, key];
+        const nextSequence = sequence ?? this.entitySequence(record.subscription.query.view, key);
+        if (nextSequence !== undefined)
+            record.sequences.set(key, nextSequence);
+        this.sortKeys(record);
+        record.isLoading = false;
+        if (!record.refreshWaiter)
+            record.isRefreshing = false;
+        record.resolved = true;
+        record.error = undefined;
+        this.touch(record);
+        this.emitUpdate(record, update);
+        if (richUpdate)
+            this.emitRichUpdate(record, richUpdate);
+    }
+    deleteGlobal(view, key, lastKnown) {
+        for (const record of this.records.values()) {
+            if (record.subscription.query.view !== view || !record.keys.includes(key))
+                continue;
+            record.keys = record.keys.filter((entry) => entry !== key);
+            record.sequences.delete(key);
+            this.touch(record);
+            this.emitUpdate(record, { type: 'delete', key });
+            this.emitRichUpdate(record, { type: 'deleted', key, lastKnown });
+        }
     }
-    getActiveSubscriptions() {
-        return Array.from(this.subscriptions.values()).map((t) => t.subscription);
+    evict(view, key) {
+        for (const record of this.records.values()) {
+            if (record.subscription.query.view !== view || !record.keys.includes(key))
+                continue;
+            record.keys = record.keys.filter((entry) => entry !== key);
+            record.sequences.delete(key);
+            this.touch(record);
+        }
+    }
+    failFrame(frame) {
+        if (frame.subscriptionId === null)
+            return;
+        this.fail(frame.subscriptionId, new AreteError(frame.message ?? frame.error ?? frame.code, frame.code, frame));
+    }
+    beginRefresh(subscriptionId, waitForSnapshot = false) {
+        const record = this.requireRecord(subscriptionId);
+        record.error = undefined;
+        record.isLoading = !record.resolved && record.subscription.snapshot.enabled;
+        record.isRefreshing = record.resolved && record.subscription.snapshot.enabled;
+        record.staged = undefined;
+        this.touch(record);
+        if (!waitForSnapshot || !record.subscription.snapshot.enabled) {
+            return Promise.resolve();
+        }
+        if (record.refreshWaiter)
+            return record.refreshWaiter.promise;
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        record.refreshWaiter = { promise, resolve, reject };
+        return promise;
+    }
+    failRefresh(subscriptionId, error) {
+        this.fail(subscriptionId, error);
+    }
+    beginReconnect() {
+        for (const record of this.records.values()) {
+            this.beginRefresh(record.subscription.subscriptionId);
+        }
+    }
+    failRefreshing(error) {
+        for (const [subscriptionId, record] of this.records) {
+            if (record.isRefreshing || record.refreshWaiter) {
+                this.fail(subscriptionId, error);
+            }
+        }
     }
     clear() {
-        for (const { subscription } of this.subscriptions.values()) {
-            this.connection.unsubscribe(subscription.view, subscription.key);
+        for (const record of this.records.values()) {
+            this.rejectRefresh(record, new AreteError('Subscription store was cleared while refreshing', 'CONNECTION_CANCELLED'));
         }
-        this.subscriptions.clear();
+        this.records.clear();
     }
-    makeSubKey(subscription) {
-        const filters = subscription.filters ? JSON.stringify(subscription.filters) : '{}';
-        return `${subscription.view}:${subscription.key ?? '*'}:${subscription.partition ?? ''}:${filters}`;
+    mergeIncremental(existing, incoming) {
+        const result = [...existing];
+        appendUnique(result, incoming);
+        return result;
+    }
+    sortKeys(record) {
+        if (record.keys.length < 2)
+            return;
+        if (!record.sort && record.mode !== 'list' && record.mode !== 'append')
+            return;
+        const field = record.sort?.field;
+        const order = record.sort?.order ?? (record.subscription.query.after ? 'asc' : 'desc');
+        const view = record.subscription.query.view;
+        record.keys = [...record.keys].sort((leftKey, rightKey) => {
+            const left = field
+                ? getNestedValue(this.storage.get(view, leftKey), field)
+                : record.sequences.get(leftKey);
+            const right = field
+                ? getNestedValue(this.storage.get(view, rightKey), field)
+                : record.sequences.get(rightKey);
+            let compared = field ? compareValues(left, right) : compareSequences(left, right);
+            if (order === 'desc')
+                compared = -compared;
+            return compared === 0 ? leftKey.localeCompare(rightKey) : compared;
+        });
+    }
+    entitySequence(view, key) {
+        const entity = this.storage.get(view, key);
+        if (entity === null || typeof entity !== 'object')
+            return undefined;
+        const value = entity;
+        const sequence = value['__seq'] ?? value['_seq'];
+        return typeof sequence === 'string' ? sequence : undefined;
+    }
+    fail(subscriptionId, error) {
+        const record = this.records.get(subscriptionId);
+        if (!record)
+            return;
+        record.error = error;
+        record.isLoading = false;
+        record.isRefreshing = false;
+        record.staged = undefined;
+        this.touch(record);
+        this.rejectRefresh(record, error);
+    }
+    resolveRefresh(record) {
+        const waiter = record.refreshWaiter;
+        if (!waiter)
+            return;
+        record.refreshWaiter = undefined;
+        waiter.resolve();
+    }
+    rejectRefresh(record, error) {
+        const waiter = record.refreshWaiter;
+        if (!waiter)
+            return;
+        record.refreshWaiter = undefined;
+        waiter.reject(error);
+    }
+    requireRecord(subscriptionId) {
+        const record = this.records.get(subscriptionId);
+        if (!record) {
+            throw new AreteError(`Unknown local subscription '${subscriptionId}'`, 'SUBSCRIPTION_NOT_FOUND');
+        }
+        return record;
+    }
+    touch(record) {
+        record.version++;
+        for (const listener of record.listeners)
+            listener();
+    }
+    emitUpdate(record, update) {
+        for (const listener of record.updateListeners)
+            listener(update);
+    }
+    emitRichUpdate(record, update) {
+        for (const listener of record.richUpdateListeners)
+            listener(update);
     }
 }
 
 const MAX_QUEUE_SIZE = 1000;
-function createUpdateStream(storage, subscriptionRegistry, subscription, keyFilter) {
+function enqueue(queue, value) {
+    if (queue.length >= MAX_QUEUE_SIZE)
+        queue.shift();
+    queue.push(value);
+}
+function createIterator(start) {
+    const queue = [];
+    let waitingResolve = null;
+    let done = false;
+    const push = (value) => {
+        if (waitingResolve) {
+            const resolve = waitingResolve;
+            waitingResolve = null;
+            resolve({ value, done: false });
+        }
+        else {
+            enqueue(queue, value);
+        }
+    };
+    const stop = start(push);
+    const cleanup = () => {
+        if (done)
+            return;
+        done = true;
+        stop();
+        waitingResolve?.({ value: undefined, done: true });
+        waitingResolve = null;
+    };
+    return {
+        async next() {
+            if (done)
+                return { value: undefined, done: true };
+            const value = queue.shift();
+            if (value !== undefined)
+                return { value, done: false };
+            return new Promise((resolve) => {
+                waitingResolve = resolve;
+            });
+        },
+        async return() {
+            cleanup();
+            return { value: undefined, done: true };
+        },
+        async throw(error) {
+            cleanup();
+            throw error;
+        },
+    };
+}
+function acquire(registry, query, snapshotEnabled) {
+    return registry.subscribe(query, snapshotEnabled);
+}
+function createUpdateStream(_storage, subscriptionRegistry, query, keyFilter, snapshotEnabled = true) {
     return {
         [Symbol.asyncIterator]() {
-            const queue = [];
-            let waitingResolve = null;
-            let unsubscribeStorage = null;
-            let unsubscribeRegistry = null;
-            let done = false;
-            const handler = (viewPath, key, update) => {
-                if (viewPath !== subscription.view)
-                    return;
-                if (keyFilter !== undefined && key !== keyFilter)
-                    return;
-                const typedUpdate = update;
-                if (waitingResolve) {
-                    const resolve = waitingResolve;
-                    waitingResolve = null;
-                    resolve({ value: typedUpdate, done: false });
-                }
-                else {
-                    if (queue.length >= MAX_QUEUE_SIZE) {
-                        queue.shift();
-                    }
-                    queue.push({
-                        update: typedUpdate,
-                        resolve: () => { },
-                    });
-                }
-            };
-            const start = () => {
-                unsubscribeStorage = storage.onUpdate(handler);
-                unsubscribeRegistry = subscriptionRegistry.subscribe(subscription);
-            };
-            const cleanup = () => {
-                done = true;
-                unsubscribeStorage?.();
-                unsubscribeRegistry?.();
-            };
-            start();
-            return {
-                async next() {
-                    if (done) {
-                        return { value: undefined, done: true };
-                    }
-                    const queued = queue.shift();
-                    if (queued) {
-                        return { value: queued.update, done: false };
-                    }
-                    return new Promise((resolve) => {
-                        waitingResolve = resolve;
-                    });
-                },
-                async return() {
-                    cleanup();
-                    return { value: undefined, done: true };
-                },
-                async throw(error) {
-                    cleanup();
-                    throw error;
-                },
-            };
+            return createIterator((push) => {
+                const lease = acquire(subscriptionRegistry, query, snapshotEnabled);
+                const unsubscribe = lease.onUpdate((update) => {
+                    if (keyFilter === undefined || update.key === keyFilter)
+                        push(update);
+                });
+                return () => {
+                    unsubscribe();
+                    lease.release();
+                };
+            });
         },
     };
 }
-function createEntityStream(storage, subscriptionRegistry, subscription, options, keyFilter) {
+function createEntityStream(_storage, subscriptionRegistry, query, options, keyFilter) {
     const schema = options?.schema;
     return {
         [Symbol.asyncIterator]() {
-            const queue = [];
-            let waitingResolve = null;
-            let unsubscribeStorage = null;
-            let unsubscribeRegistry = null;
-            let done = false;
-            const handler = (viewPath, key, update) => {
-                if (viewPath !== subscription.view)
-                    return;
-                if (keyFilter !== undefined && key !== keyFilter)
-                    return;
-                if (update.type === 'deleted')
-                    return;
-                const entity = (update.type === 'created' ? update.data : update.after);
-                let output;
-                if (schema) {
-                    const parsed = schema.safeParse(entity);
-                    if (!parsed.success) {
+            return createIterator((push) => {
+                const lease = acquire(subscriptionRegistry, query, options?.withSnapshot ?? true);
+                const emit = (entity) => {
+                    if (!schema) {
+                        push(entity);
                         return;
                     }
-                    output = parsed.data;
-                }
-                else {
-                    output = entity;
-                }
-                if (waitingResolve) {
-                    const resolve = waitingResolve;
-                    waitingResolve = null;
-                    resolve({ value: output, done: false });
-                }
-                else {
-                    if (queue.length >= MAX_QUEUE_SIZE) {
-                        queue.shift();
-                    }
-                    queue.push(output);
+                    const parsed = schema.safeParse(entity);
+                    if (parsed.success)
+                        push(parsed.data);
+                };
+                for (const [index, entity] of lease.getSnapshot().data.entries()) {
+                    const key = lease.getSnapshot().keys[index];
+                    if (keyFilter === undefined || key === keyFilter)
+                        emit(entity);
                 }
-            };
-            const start = () => {
-                unsubscribeStorage = storage.onRichUpdate(handler);
-                unsubscribeRegistry = subscriptionRegistry.subscribe(subscription);
-            };
-            const cleanup = () => {
-                done = true;
-                unsubscribeStorage?.();
-                unsubscribeRegistry?.();
-            };
-            start();
-            const iterator = {
-                async next() {
-                    if (done) {
-                        return { value: undefined, done: true };
-                    }
-                    const queued = queue.shift();
-                    if (queued) {
-                        return { value: queued, done: false };
-                    }
-                    return new Promise((resolve) => {
-                        waitingResolve = resolve;
-                    });
-                },
-                async return() {
-                    cleanup();
-                    return { value: undefined, done: true };
-                },
-                async throw(error) {
-                    cleanup();
-                    throw error;
-                },
-            };
-            return iterator;
+                const unsubscribe = lease.onRichUpdate((update) => {
+                    if (keyFilter !== undefined && update.key !== keyFilter)
+                        return;
+                    if (update.type === 'created')
+                        emit(update.data);
+                    if (update.type === 'updated')
+                        emit(update.after);
+                });
+                return () => {
+                    unsubscribe();
+                    lease.release();
+                };
+            });
         },
     };
 }
-function createRichUpdateStream(storage, subscriptionRegistry, subscription, keyFilter) {
+function createRichUpdateStream(_storage, subscriptionRegistry, query, keyFilter, snapshotEnabled = true) {
     return {
         [Symbol.asyncIterator]() {
-            const queue = [];
-            let waitingResolve = null;
-            let unsubscribeStorage = null;
-            let unsubscribeRegistry = null;
-            let done = false;
-            const handler = (viewPath, key, update) => {
-                if (viewPath !== subscription.view)
-                    return;
-                if (keyFilter !== undefined && key !== keyFilter)
-                    return;
-                const typedUpdate = update;
-                if (waitingResolve) {
-                    const resolve = waitingResolve;
-                    waitingResolve = null;
-                    resolve({ value: typedUpdate, done: false });
-                }
-                else {
-                    if (queue.length >= MAX_QUEUE_SIZE) {
-                        queue.shift();
-                    }
-                    queue.push({
-                        update: typedUpdate,
-                        resolve: () => { },
-                    });
-                }
-            };
-            const start = () => {
-                unsubscribeStorage = storage.onRichUpdate(handler);
-                unsubscribeRegistry = subscriptionRegistry.subscribe(subscription);
-            };
-            const cleanup = () => {
-                done = true;
-                unsubscribeStorage?.();
-                unsubscribeRegistry?.();
-            };
-            start();
-            return {
-                async next() {
-                    if (done) {
-                        return { value: undefined, done: true };
-                    }
-                    const queued = queue.shift();
-                    if (queued) {
-                        return { value: queued.update, done: false };
-                    }
-                    return new Promise((resolve) => {
-                        waitingResolve = resolve;
-                    });
-                },
-                async return() {
-                    cleanup();
-                    return { value: undefined, done: true };
-                },
-                async throw(error) {
-                    cleanup();
-                    throw error;
-                },
-            };
+            return createIterator((push) => {
+                const lease = acquire(subscriptionRegistry, query, snapshotEnabled);
+                const unsubscribe = lease.onRichUpdate((update) => {
+                    if (keyFilter === undefined || update.key === keyFilter)
+                        push(update);
+                });
+                return () => {
+                    unsubscribe();
+                    lease.release();
+                };
+            });
         },
     };
 }
 
+function queryOptions(options) {
+    const { schema: _schema, withSnapshot, ...query } = options ?? {};
+    return { query, snapshotEnabled: withSnapshot ?? true };
+}
+function serializeViewKeyValue(value, view, field) {
+    const location = field === undefined ? `view '${view}'` : `key field '${field}' for view '${view}'`;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString(10);
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value)) {
+            throw new TypeError(`${location} must be a safe integer`);
+        }
+        return value.toString(10);
+    }
+    throw new TypeError(`${location} must be a string, safe integer, or bigint`);
+}
+function serializeViewKey(viewDef, key) {
+    const keyFields = viewDef.keyFields ?? [];
+    if (keyFields.length === 0) {
+        return serializeViewKeyValue(key, viewDef.view);
+    }
+    if (keyFields.length !== 1) {
+        throw new TypeError(`View '${viewDef.view}' has an unsupported composite key with fields [${keyFields.join(', ')}]`);
+    }
+    if (key === null || typeof key !== 'object' || Array.isArray(key)) {
+        throw new TypeError(`View '${viewDef.view}' requires an object key`);
+    }
+    const field = keyFields[0];
+    if (!Object.prototype.hasOwnProperty.call(key, field)) {
+        throw new TypeError(`View '${viewDef.view}' key is missing field '${field}'`);
+    }
+    return serializeViewKeyValue(key[field], viewDef.view, field);
+}
 function createTypedStateView(viewDef, storage, subscriptionRegistry) {
+    const wireKey = (key) => serializeViewKey(viewDef, key);
     return {
         use(key, options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, options, key);
+            const serializedKey = wireKey(key);
+            const { query } = queryOptions(options);
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, options, serializedKey);
         },
         watch(key, options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, key);
+            const serializedKey = wireKey(key);
+            const { query, snapshotEnabled } = queryOptions(options);
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, serializedKey, snapshotEnabled);
         },
         watchRich(key, options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, key);
+            const serializedKey = wireKey(key);
+            const { query, snapshotEnabled } = queryOptions(options);
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, serializedKey, snapshotEnabled);
         },
-        async get(key) {
-            return storage.get(viewDef.view, key);
+        async get(key, options) {
+            return this.getSync(key, options) ?? null;
         },
-        getSync(key) {
-            return storage.getSync(viewDef.view, key);
+        getSync(key, options) {
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = subscriptionRegistry.getSnapshot({
+                view: viewDef.view,
+                key: wireKey(key),
+                ...query,
+            }, snapshotEnabled);
+            return snapshot ? snapshot.data[0] ?? null : undefined;
         },
     };
 }
 function createTypedListView(viewDef, storage, subscriptionRegistry) {
     return {
         use(options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions }, options);
+            const { query } = queryOptions(options);
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, options);
         },
         watch(options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions });
+            const { query, snapshotEnabled } = queryOptions(options);
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, undefined, snapshotEnabled);
         },
         watchRich(options) {
-            const { schema: _schema, ...subscriptionOptions } = options ?? {};
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions });
+            const { query, snapshotEnabled } = queryOptions(options);
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, undefined, snapshotEnabled);
         },
-        async get() {
-            return storage.getAll(viewDef.view);
+        async get(options) {
+            return this.getSync(options) ?? [];
         },
-        getSync() {
-            return storage.getAllSync(viewDef.view);
+        getSync(options) {
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = subscriptionRegistry.getSnapshot({ view: viewDef.view, ...query }, snapshotEnabled);
+            return snapshot ? [...snapshot.data] : undefined;
         },
     };
 }
@@ -1869,7 +2965,38 @@ function decodeBase64(encoded) {
     if (bufferCtor) {
         return new Uint8Array(bufferCtor.from(encoded, 'base64'));
     }
-    throw new Error('No base64 decoder available in this environment');
+    throw new Error('No base64 decoder available in this environment');
+}
+function decimalU64(value, field) {
+    if (!/^\d+$/.test(value)) {
+        throw new TypeError(`${field} must be a decimal u64 string`);
+    }
+    const parsed = BigInt(value);
+    if (parsed > 18446744073709551615n) {
+        throw new RangeError(`${field} exceeds u64`);
+    }
+    return parsed;
+}
+function serializeContextSlot(value) {
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new RangeError('minContextSlot must be a non-negative safe integer or bigint');
+        }
+        return String(value);
+    }
+    if (value < 0n || value > 18446744073709551615n) {
+        throw new RangeError('minContextSlot must fit in u64');
+    }
+    return value.toString();
+}
+function withContextSlot(input, options) {
+    if (options?.minContextSlot === undefined) {
+        return input;
+    }
+    return {
+        ...input,
+        minContextSlot: serializeContextSlot(options.minContextSlot),
+    };
 }
 function deriveHttpEndpoint(wsUrl) {
     try {
@@ -1900,6 +3027,19 @@ function createChainClient(httpBaseUrl, fetchImpl) {
             const body = await parseReadResponse(response, path);
             return body.lamports;
         },
+        async nativeBalance(address, options) {
+            const path = '/chain/native-balance';
+            const response = await fetchImpl(joinUrl(httpBaseUrl, path), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(withContextSlot({ address }, options)),
+            });
+            const body = await parseReadResponse(response, path);
+            return {
+                lamports: decimalU64(body.lamports, 'lamports'),
+                contextSlot: decimalU64(body.contextSlot, 'contextSlot'),
+            };
+        },
         async minimumBalanceForRentExemption(space) {
             const path = `/chain/rent-exemption/${encodeURIComponent(String(space))}`;
             const response = await fetchImpl(joinUrl(httpBaseUrl, path));
@@ -1936,18 +3076,469 @@ function createChainClient(httpBaseUrl, fetchImpl) {
             const response = await fetchImpl(joinUrl(httpBaseUrl, path));
             return parseReadResponse(response, path);
         },
-        async balance(input) {
+        async balance(input, options) {
             const path = '/chain/balances';
             const response = await fetchImpl(joinUrl(httpBaseUrl, path), {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
-                body: JSON.stringify(input),
+                body: JSON.stringify(withContextSlot(input, options)),
             });
-            return parseReadResponse(response, path);
+            const body = await parseReadResponse(response, path);
+            return {
+                ...body,
+                contextSlot: decimalU64(body.contextSlot, 'contextSlot'),
+            };
         },
     };
 }
 
+/*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) */
+/**
+ * 4KB JS implementation of ed25519 EdDSA signatures.
+ * Compliant with RFC8032, FIPS 186-5 & ZIP215.
+ * @module
+ * @example
+ * ```js
+import * as ed from '@noble/ed25519';
+(async () => {
+  const privKey = ed.utils.randomPrivateKey();
+  const message = Uint8Array.from([0xab, 0xbc, 0xcd, 0xde]);
+  const pubKey = await ed.getPublicKeyAsync(privKey); // Sync methods are also present
+  const signature = await ed.signAsync(message, privKey);
+  const isValid = await ed.verifyAsync(signature, message, pubKey);
+})();
+```
+ */
+/**
+ * Curve params. ed25519 is twisted edwards curve. Equation is −x² + y² = -a + dx²y².
+ * * P = `2n**255n - 19n` // field over which calculations are done
+ * * N = `2n**252n + 27742317777372353535851937790883648493n` // group order, amount of curve points
+ * * h = 8 // cofactor
+ * * a = `Fp.create(BigInt(-1))` // equation param
+ * * d = -121665/121666 a.k.a. `Fp.neg(121665 * Fp.inv(121666))` // equation param
+ * * Gx, Gy are coordinates of Generator / base point
+ */
+const ed25519_CURVE = {
+    p: 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedn,
+    n: 0x1000000000000000000000000000000014def9dea2f79cd65812631a5cf5d3edn,
+    h: 8n,
+    a: 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffecn,
+    d: 0x52036cee2b6ffe738cc740797779e89800700a4d4141d8ab75eb4dca135978a3n,
+    Gx: 0x216936d3cd6e53fec0a4e231fdd6dc5c692cc7609525a7b2c9562d608f25d51an,
+    Gy: 0x6666666666666666666666666666666666666666666666666666666666666658n,
+};
+const { p: P, n: N, Gx, Gy, a: _a, d: _d } = ed25519_CURVE;
+const h = 8n; // cofactor
+const L = 32; // field / group byte length
+const L2 = 64;
+// Helpers and Precomputes sections are reused between libraries
+// ## Helpers
+// ----------
+// error helper, messes-up stack trace
+const err = (m = '') => {
+    throw new Error(m);
+};
+const isBig = (n) => typeof n === 'bigint'; // is big integer
+const isStr = (s) => typeof s === 'string'; // is string
+const isBytes = (a) => a instanceof Uint8Array || (ArrayBuffer.isView(a) && a.constructor.name === 'Uint8Array');
+/** assert is Uint8Array (of specific length) */
+const abytes = (a, l) => !isBytes(a) || (typeof l === 'number' && l > 0 && a.length !== l)
+    ? err('Uint8Array expected')
+    : a;
+/** create Uint8Array */
+const u8n = (len) => new Uint8Array(len);
+const u8fr = (buf) => Uint8Array.from(buf);
+const padh = (n, pad) => n.toString(16).padStart(pad, '0');
+const bytesToHex = (b) => Array.from(abytes(b))
+    .map((e) => padh(e, 2))
+    .join('');
+const C = { _0: 48, _9: 57, A: 65, F: 70, a: 97, f: 102 }; // ASCII characters
+const _ch = (ch) => {
+    if (ch >= C._0 && ch <= C._9)
+        return ch - C._0; // '2' => 50-48
+    if (ch >= C.A && ch <= C.F)
+        return ch - (C.A - 10); // 'B' => 66-(65-10)
+    if (ch >= C.a && ch <= C.f)
+        return ch - (C.a - 10); // 'b' => 98-(97-10)
+    return;
+};
+const hexToBytes = (hex) => {
+    const e = 'hex invalid';
+    if (!isStr(hex))
+        return err(e);
+    const hl = hex.length;
+    const al = hl / 2;
+    if (hl % 2)
+        return err(e);
+    const array = u8n(al);
+    for (let ai = 0, hi = 0; ai < al; ai++, hi += 2) {
+        // treat each char as ASCII
+        const n1 = _ch(hex.charCodeAt(hi)); // parse first char, multiply it by 16
+        const n2 = _ch(hex.charCodeAt(hi + 1)); // parse second char
+        if (n1 === undefined || n2 === undefined)
+            return err(e);
+        array[ai] = n1 * 16 + n2; // example: 'A9' => 10*16 + 9
+    }
+    return array;
+};
+/** normalize hex or ui8a to ui8a */
+const toU8 = (a, len) => abytes(isStr(a) ? hexToBytes(a) : u8fr(abytes(a)), len);
+const big = BigInt;
+const arange = (n, min, max, msg = 'bad number: out of range') => isBig(n) && min <= n && n < max ? n : err(msg);
+/** modular division */
+const M = (a, b = P) => {
+    const r = a % b;
+    return r >= 0n ? r : b + r;
+};
+/** Modular inversion using eucledian GCD (non-CT). No negative exponent for now. */
+// prettier-ignore
+const invert = (num, md) => {
+    if (num === 0n || md <= 0n)
+        err('no inverse n=' + num + ' mod=' + md);
+    let a = M(num, md), b = md, x = 0n, u = 1n;
+    while (a !== 0n) {
+        const q = b / a, r = b % a;
+        const m = x - u * q;
+        b = a, a = r, x = u, u = m;
+    }
+    return b === 1n ? M(x, md) : err('no inverse'); // b is gcd at this point
+};
+const apoint = (p) => (p instanceof Point ? p : err('Point expected'));
+// ## End of Helpers
+// -----------------
+const B256 = 2n ** 256n;
+/** Point in XYZT extended coordinates. */
+class Point {
+    static BASE;
+    static ZERO;
+    ex;
+    ey;
+    ez;
+    et;
+    constructor(ex, ey, ez, et) {
+        const max = B256;
+        this.ex = arange(ex, 0n, max);
+        this.ey = arange(ey, 0n, max);
+        this.ez = arange(ez, 1n, max);
+        this.et = arange(et, 0n, max);
+        Object.freeze(this);
+    }
+    static fromAffine(p) {
+        return new Point(p.x, p.y, 1n, M(p.x * p.y));
+    }
+    /** RFC8032 5.1.3: Uint8Array to Point. */
+    static fromBytes(hex, zip215 = false) {
+        const d = _d;
+        // Copy array to not mess it up.
+        const normed = u8fr(abytes(hex, L));
+        // adjust first LE byte = last BE byte
+        const lastByte = hex[31];
+        normed[31] = lastByte & ~0x80;
+        const y = bytesToNumLE(normed);
+        // zip215=true:           0 <= y < 2^256
+        // zip215=false, RFC8032: 0 <= y < 2^255-19
+        const max = zip215 ? B256 : P;
+        arange(y, 0n, max);
+        const y2 = M(y * y); // y²
+        const u = M(y2 - 1n); // u=y²-1
+        const v = M(d * y2 + 1n); // v=dy²+1
+        let { isValid, value: x } = uvRatio(u, v); // (uv³)(uv⁷)^(p-5)/8; square root
+        if (!isValid)
+            err('bad point: y not sqrt'); // not square root: bad point
+        const isXOdd = (x & 1n) === 1n; // adjust sign of x coordinate
+        const isLastByteOdd = (lastByte & 0x80) !== 0; // x_0, last bit
+        if (!zip215 && x === 0n && isLastByteOdd)
+            err('bad point: x==0, isLastByteOdd'); // x=0, x_0=1
+        if (isLastByteOdd !== isXOdd)
+            x = M(-x);
+        return new Point(x, y, 1n, M(x * y)); // Z=1, T=xy
+    }
+    /** Checks if the point is valid and on-curve. */
+    assertValidity() {
+        const a = _a;
+        const d = _d;
+        const p = this;
+        if (p.is0())
+            throw new Error('bad point: ZERO'); // TODO: optimize, with vars below?
+        // Equation in affine coordinates: ax² + y² = 1 + dx²y²
+        // Equation in projective coordinates (X/Z, Y/Z, Z):  (aX² + Y²)Z² = Z⁴ + dX²Y²
+        const { ex: X, ey: Y, ez: Z, et: T } = p;
+        const X2 = M(X * X); // X²
+        const Y2 = M(Y * Y); // Y²
+        const Z2 = M(Z * Z); // Z²
+        const Z4 = M(Z2 * Z2); // Z⁴
+        const aX2 = M(X2 * a); // aX²
+        const left = M(Z2 * M(aX2 + Y2)); // (aX² + Y²)Z²
+        const right = M(Z4 + M(d * M(X2 * Y2))); // Z⁴ + dX²Y²
+        if (left !== right)
+            throw new Error('bad point: equation left != right (1)');
+        // In Extended coordinates we also have T, which is x*y=T/Z: check X*Y == Z*T
+        const XY = M(X * Y);
+        const ZT = M(Z * T);
+        if (XY !== ZT)
+            throw new Error('bad point: equation left != right (2)');
+        return this;
+    }
+    /** Equality check: compare points P&Q. */
+    equals(other) {
+        const { ex: X1, ey: Y1, ez: Z1 } = this;
+        const { ex: X2, ey: Y2, ez: Z2 } = apoint(other); // checks class equality
+        const X1Z2 = M(X1 * Z2);
+        const X2Z1 = M(X2 * Z1);
+        const Y1Z2 = M(Y1 * Z2);
+        const Y2Z1 = M(Y2 * Z1);
+        return X1Z2 === X2Z1 && Y1Z2 === Y2Z1;
+    }
+    is0() {
+        return this.equals(I);
+    }
+    /** Flip point over y coordinate. */
+    negate() {
+        return new Point(M(-this.ex), this.ey, this.ez, M(-this.et));
+    }
+    /** Point doubling. Complete formula. Cost: `4M + 4S + 1*a + 6add + 1*2`. */
+    double() {
+        const { ex: X1, ey: Y1, ez: Z1 } = this;
+        const a = _a;
+        // https://hyperelliptic.org/EFD/g1p/auto-twisted-extended.html#doubling-dbl-2008-hwcd
+        const A = M(X1 * X1);
+        const B = M(Y1 * Y1);
+        const C = M(2n * M(Z1 * Z1));
+        const D = M(a * A);
+        const x1y1 = X1 + Y1;
+        const E = M(M(x1y1 * x1y1) - A - B);
+        const G = D + B;
+        const F = G - C;
+        const H = D - B;
+        const X3 = M(E * F);
+        const Y3 = M(G * H);
+        const T3 = M(E * H);
+        const Z3 = M(F * G);
+        return new Point(X3, Y3, Z3, T3);
+    }
+    /** Point addition. Complete formula. Cost: `8M + 1*k + 8add + 1*2`. */
+    add(other) {
+        const { ex: X1, ey: Y1, ez: Z1, et: T1 } = this;
+        const { ex: X2, ey: Y2, ez: Z2, et: T2 } = apoint(other); // doesn't check if other on-curve
+        const a = _a;
+        const d = _d;
+        // https://hyperelliptic.org/EFD/g1p/auto-twisted-extended-1.html#addition-add-2008-hwcd-3
+        const A = M(X1 * X2);
+        const B = M(Y1 * Y2);
+        const C = M(T1 * d * T2);
+        const D = M(Z1 * Z2);
+        const E = M((X1 + Y1) * (X2 + Y2) - A - B);
+        const F = M(D - C);
+        const G = M(D + C);
+        const H = M(B - a * A);
+        const X3 = M(E * F);
+        const Y3 = M(G * H);
+        const T3 = M(E * H);
+        const Z3 = M(F * G);
+        return new Point(X3, Y3, Z3, T3);
+    }
+    /**
+     * Point-by-scalar multiplication. Scalar must be in range 1 <= n < CURVE.n.
+     * Uses {@link wNAF} for base point.
+     * Uses fake point to mitigate side-channel leakage.
+     * @param n scalar by which point is multiplied
+     * @param safe safe mode guards against timing attacks; unsafe mode is faster
+     */
+    multiply(n, safe = true) {
+        if (!safe && (n === 0n || this.is0()))
+            return I;
+        arange(n, 1n, N);
+        if (n === 1n)
+            return this;
+        if (this.equals(G))
+            return wNAF(n).p;
+        // init result point & fake point
+        let p = I;
+        let f = G;
+        for (let d = this; n > 0n; d = d.double(), n >>= 1n) {
+            // if bit is present, add to point
+            // if not present, add to fake, for timing safety
+            if (n & 1n)
+                p = p.add(d);
+            else if (safe)
+                f = f.add(d);
+        }
+        return p;
+    }
+    /** Convert point to 2d xy affine point. (X, Y, Z) ∋ (x=X/Z, y=Y/Z) */
+    toAffine() {
+        const { ex: x, ey: y, ez: z } = this;
+        // fast-paths for ZERO point OR Z=1
+        if (this.equals(I))
+            return { x: 0n, y: 1n };
+        const iz = invert(z, P);
+        // (Z * Z^-1) must be 1, otherwise bad math
+        if (M(z * iz) !== 1n)
+            err('invalid inverse');
+        // x = X*Z^-1; y = Y*Z^-1
+        return { x: M(x * iz), y: M(y * iz) };
+    }
+    toBytes() {
+        const { x, y } = this.assertValidity().toAffine();
+        const b = numTo32bLE(y);
+        // store sign in first LE byte
+        b[31] |= x & 1n ? 0x80 : 0;
+        return b;
+    }
+    toHex() {
+        return bytesToHex(this.toBytes());
+    } // encode to hex string
+    clearCofactor() {
+        return this.multiply(big(h), false);
+    }
+    isSmallOrder() {
+        return this.clearCofactor().is0();
+    }
+    isTorsionFree() {
+        // multiply by big number CURVE.n
+        let p = this.multiply(N / 2n, false).double(); // ensures the point is not "bad".
+        if (N % 2n)
+            p = p.add(this); // P^(N+1) // P*N == (P*(N/2))*2+P
+        return p.is0();
+    }
+    static fromHex(hex, zip215) {
+        return Point.fromBytes(toU8(hex), zip215);
+    }
+    get x() {
+        return this.toAffine().x;
+    }
+    get y() {
+        return this.toAffine().y;
+    }
+    toRawBytes() {
+        return this.toBytes();
+    }
+}
+/** Generator / base point */
+const G = new Point(Gx, Gy, 1n, M(Gx * Gy));
+/** Identity / zero point */
+const I = new Point(0n, 1n, 1n, 0n);
+// Static aliases
+Point.BASE = G;
+Point.ZERO = I;
+const numTo32bLE = (num) => hexToBytes(padh(arange(num, 0n, B256), L2)).reverse();
+const bytesToNumLE = (b) => big('0x' + bytesToHex(u8fr(abytes(b)).reverse()));
+const pow2 = (x, power) => {
+    // pow2(x, 4) == x^(2^4)
+    let r = x;
+    while (power-- > 0n) {
+        r *= r;
+        r %= P;
+    }
+    return r;
+};
+// prettier-ignore
+const pow_2_252_3 = (x) => {
+    const x2 = (x * x) % P; // x^2,       bits 1
+    const b2 = (x2 * x) % P; // x^3,       bits 11
+    const b4 = (pow2(b2, 2n) * b2) % P; // x^(2^4-1), bits 1111
+    const b5 = (pow2(b4, 1n) * x) % P; // x^(2^5-1), bits 11111
+    const b10 = (pow2(b5, 5n) * b5) % P; // x^(2^10)
+    const b20 = (pow2(b10, 10n) * b10) % P; // x^(2^20)
+    const b40 = (pow2(b20, 20n) * b20) % P; // x^(2^40)
+    const b80 = (pow2(b40, 40n) * b40) % P; // x^(2^80)
+    const b160 = (pow2(b80, 80n) * b80) % P; // x^(2^160)
+    const b240 = (pow2(b160, 80n) * b80) % P; // x^(2^240)
+    const b250 = (pow2(b240, 10n) * b10) % P; // x^(2^250)
+    const pow_p_5_8 = (pow2(b250, 2n) * x) % P; // < To pow to (p+3)/8, multiply it by x.
+    return { pow_p_5_8, b2 };
+};
+const RM1 = 0x2b8324804fc1df0b2b4d00993dfbd7a72f431806ad2fe478c4ee1b274a0ea0b0n; // √-1
+// for sqrt comp
+// prettier-ignore
+const uvRatio = (u, v) => {
+    const v3 = M(v * v * v); // v³
+    const v7 = M(v3 * v3 * v); // v⁷
+    const pow = pow_2_252_3(u * v7).pow_p_5_8; // (uv⁷)^(p-5)/8
+    let x = M(u * v3 * pow); // (uv³)(uv⁷)^(p-5)/8
+    const vx2 = M(v * x * x); // vx²
+    const root1 = x; // First root candidate
+    const root2 = M(x * RM1); // Second root candidate; RM1 is √-1
+    const useRoot1 = vx2 === u; // If vx² = u (mod p), x is a square root
+    const useRoot2 = vx2 === M(-u); // If vx² = -u, set x <-- x * 2^((p-1)/4)
+    const noRoot = vx2 === M(-u * RM1); // There is no valid root, vx² = -u√-1
+    if (useRoot1)
+        x = root1;
+    if (useRoot2 || noRoot)
+        x = root2; // We return root2 anyway, for const-time
+    if ((M(x) & 1n) === 1n)
+        x = M(-x); // edIsNegative
+    return { isValid: useRoot1 || useRoot2, value: x };
+};
+// ## Precomputes
+// --------------
+const W = 8; // W is window size
+const scalarBits = 256;
+const pwindows = Math.ceil(scalarBits / W) + 1; // 33 for W=8
+const pwindowSize = 2 ** (W - 1); // 128 for W=8
+const precompute = () => {
+    const points = [];
+    let p = G;
+    let b = p;
+    for (let w = 0; w < pwindows; w++) {
+        b = p;
+        points.push(b);
+        for (let i = 1; i < pwindowSize; i++) {
+            b = b.add(p);
+            points.push(b);
+        } // i=1, bc we skip 0
+        p = b.double();
+    }
+    return points;
+};
+let Gpows = undefined; // precomputes for base point G
+// const-time negate
+const ctneg = (cnd, p) => {
+    const n = p.negate();
+    return cnd ? n : p;
+};
+/**
+ * Precomputes give 12x faster getPublicKey(), 10x sign(), 2x verify() by
+ * caching multiples of G (base point). Cache is stored in 32MB of RAM.
+ * Any time `G.multiply` is done, precomputes are used.
+ * Not used for getSharedSecret, which instead multiplies random pubkey `P.multiply`.
+ *
+ * w-ary non-adjacent form (wNAF) precomputation method is 10% slower than windowed method,
+ * but takes 2x less RAM. RAM reduction is possible by utilizing `.subtract`.
+ *
+ * !! Precomputes can be disabled by commenting-out call of the wNAF() inside Point#multiply().
+ */
+const wNAF = (n) => {
+    const comp = Gpows || (Gpows = precompute());
+    let p = I;
+    let f = G; // f must be G, or could become I in the end
+    const pow_2_w = 2 ** W; // 256 for W=8
+    const maxNum = pow_2_w; // 256 for W=8
+    const mask = big(pow_2_w - 1); // 255 for W=8 == mask 0b11111111
+    const shiftBy = big(W); // 8 for W=8
+    for (let w = 0; w < pwindows; w++) {
+        let wbits = Number(n & mask); // extract W bits.
+        n >>= shiftBy; // shift number by W bits.
+        if (wbits > pwindowSize) {
+            wbits -= maxNum;
+            n += 1n;
+        } // split if bits > max: +224 => 256-32
+        const off = w * pwindowSize;
+        const offF = off; // offsets, evaluate both
+        const offP = off + Math.abs(wbits) - 1;
+        const isEven = w % 2 !== 0; // conditions, evaluate both
+        const isNeg = wbits < 0;
+        if (wbits === 0) {
+            // off == I: can't add it. Adding random offF instead.
+            f = f.add(ctneg(isEven, comp[offF])); // bits are 0: add garbage to fake point
+        }
+        else {
+            p = p.add(ctneg(isNeg, comp[offP])); // bits are 1: add to result point
+        }
+    }
+    return { p, f }; // return both real and fake points for JIT
+};
+
 /**
  * PDA (Program Derived Address) derivation utilities.
  *
@@ -2899,6 +4490,19 @@ function serializeArray(values, elementType, length) {
 /**
  * Parses and handles instruction errors.
  */
+/**
+ * Structured transaction failure thrown by adapters and the core executor.
+ */
+class TransactionExecutionError extends Error {
+    constructor(outcome, message) {
+        super(message ?? errorMessage(outcome.cause, defaultOutcomeMessage(outcome)));
+        this.name = 'TransactionExecutionError';
+        this.outcome = outcome;
+        this.cause = outcome.cause;
+        this.signature = 'signature' in outcome ? outcome.signature : undefined;
+        this.slot = 'slot' in outcome ? outcome.slot : undefined;
+    }
+}
 /**
  * Parses an error returned from a Solana transaction.
  *
@@ -2907,44 +4511,84 @@ function serializeArray(values, elementType, length) {
  * @returns Parsed program error or null if not a program error
  */
 function parseInstructionError(error, errorMetadata) {
-    if (!error) {
-        return null;
+    return parseInstructionErrorMatch(error, errorMetadata)?.programError ?? null;
+}
+function extractErrorCodes(error, seen, results) {
+    if (typeof error !== 'object' || error === null) {
+        return;
     }
-    const errorCode = extractErrorCode(error);
-    if (errorCode === null) {
-        return null;
+    if (seen.has(error)) {
+        return;
     }
-    const metadata = errorMetadata.find(e => e.code === errorCode);
-    if (metadata) {
-        return {
-            code: metadata.code,
-            name: metadata.name,
-            message: metadata.msg,
-        };
+    seen.add(error);
+    if (error instanceof InstructionError && error.programError) {
+        results.push({ code: error.programError.code, source: 'program-error' });
+        return;
     }
-    return {
-        code: errorCode,
-        name: `CustomError${errorCode}`,
-        message: `Unknown error with code ${errorCode}`,
-    };
-}
-function extractErrorCode(error) {
-    if (typeof error !== 'object' || error === null) {
-        return null;
+    if (error instanceof TransactionExecutionError) {
+        const outcomeCode = error.outcome.status === 'chain-failed'
+            ? error.outcome.programError?.code
+            : undefined;
+        if (outcomeCode !== undefined) {
+            results.push({ code: outcomeCode, source: 'program-error' });
+            return;
+        }
     }
     const errorObj = error;
     // Check for InstructionError format
-    if (errorObj.InstructionError) {
+    if (Array.isArray(errorObj.InstructionError)) {
         const instructionError = errorObj.InstructionError;
-        if (instructionError[1]?.Custom !== undefined) {
-            return instructionError[1].Custom;
+        const detail = instructionError[1];
+        if (typeof detail === 'object' && detail !== null) {
+            const custom = detail.Custom;
+            if (typeof custom === 'number') {
+                results.push({ code: custom, source: 'instruction-error' });
+            }
+        }
+    }
+    const programError = errorObj.programError;
+    if (typeof programError === 'object' && programError !== null) {
+        const code = programError.code;
+        if (typeof code === 'number') {
+            results.push({ code, source: 'program-error' });
         }
     }
-    // Check for direct code
     if (typeof errorObj.code === 'number') {
-        return errorObj.code;
+        results.push({ code: errorObj.code, source: 'direct-code' });
     }
-    return null;
+    for (const key of ['cause', 'error', 'err', 'value', 'data', 'outcome', 'transactionError']) {
+        extractErrorCodes(errorObj[key], seen, results);
+    }
+}
+function parseInstructionErrorMatch(error, errorMetadata) {
+    if (!error) {
+        return null;
+    }
+    const candidates = [];
+    extractErrorCodes(error, new Set(), candidates);
+    const selected = candidates.find((candidate) => candidate.source === 'instruction-error')
+        ?? candidates.find((candidate) => candidate.source === 'program-error')
+        ?? candidates.find((candidate) => errorMetadata.some((metadata) => metadata.code === candidate.code))
+        ?? candidates[0];
+    if (!selected) {
+        return null;
+    }
+    const metadata = errorMetadata.find((entry) => entry.code === selected.code);
+    const programError = metadata
+        ? {
+            code: metadata.code,
+            name: metadata.name,
+            message: metadata.msg,
+        }
+        : {
+            code: selected.code,
+            name: `CustomError${selected.code}`,
+            message: `Unknown error with code ${selected.code}`,
+        };
+    return {
+        programError,
+        deterministic: selected.source !== 'direct-code' || metadata !== undefined,
+    };
 }
 /**
  * Formats an error for display.
@@ -2960,12 +4604,185 @@ function formatProgramError(error) {
  * could be parsed against the handler's IDL error definitions.
  */
 class InstructionError extends Error {
-    constructor(message, programError, cause) {
+    constructor(message, programError, cause, outcome) {
         super(message);
         this.name = 'InstructionError';
         this.programError = programError;
-        this.cause = cause;
+        if (outcome) {
+            this.outcome = outcome;
+        }
+        else {
+            const context = getTransactionFailureOutcome(cause);
+            this.outcome = {
+                status: 'chain-failed',
+                phase: 'chain',
+                signature: context && 'signature' in context ? context.signature : undefined,
+                slot: context && 'slot' in context ? context.slot : undefined,
+                programError: programError ?? undefined,
+                cause: context?.cause ?? cause,
+            };
+        }
+        this.cause = this.outcome.cause;
+        this.signature = this.outcome.signature;
+        this.slot = this.outcome.slot;
+    }
+}
+function defaultOutcomeMessage(outcome) {
+    switch (outcome.status) {
+        case 'not-submitted':
+            return `Transaction was not submitted during ${outcome.phase}`;
+        case 'submitted-unknown':
+            return `Transaction ${outcome.signature} was submitted but its status is unknown`;
+        case 'chain-failed':
+            return outcome.signature
+                ? `Transaction ${outcome.signature} failed on chain`
+                : 'Transaction failed on chain';
+    }
+}
+function errorMessage(cause, fallback) {
+    return cause instanceof Error && cause.message ? cause.message : fallback;
+}
+function isFailureOutcome(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return ((candidate.status === 'not-submitted'
+        || candidate.status === 'submitted-unknown'
+        || candidate.status === 'chain-failed')
+        && typeof candidate.phase === 'string'
+        && 'cause' in candidate);
+}
+/** Find a structured transaction failure through nested error causes. */
+function getTransactionFailureOutcome(error) {
+    const seen = new Set();
+    let current = error;
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof TransactionExecutionError || current instanceof InstructionError) {
+            return current.outcome;
+        }
+        const candidate = current;
+        if (isFailureOutcome(candidate.outcome)) {
+            return candidate.outcome;
+        }
+        current = candidate.cause;
+    }
+    return null;
+}
+function extractTransactionContext(error) {
+    const seen = new Set();
+    let current = error;
+    let signature;
+    let slot;
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const candidate = current;
+        if (!signature && typeof candidate.signature === 'string') {
+            signature = candidate.signature;
+        }
+        if (slot === undefined && typeof candidate.slot === 'number') {
+            slot = candidate.slot;
+        }
+        if (isFailureOutcome(candidate.outcome)) {
+            if (!signature && 'signature' in candidate.outcome) {
+                signature = candidate.outcome.signature;
+            }
+            if (slot === undefined && 'slot' in candidate.outcome) {
+                slot = candidate.outcome.slot;
+            }
+        }
+        current = candidate.cause;
+    }
+    return { signature, slot };
+}
+function isWalletRejection(error) {
+    const seen = new Set();
+    let current = error;
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const candidate = current;
+        if (candidate.code === 4001
+            || candidate.code === '4001'
+            || candidate.code === 'ACTION_REJECTED') {
+            return true;
+        }
+        const name = String(candidate.name ?? '');
+        if (/^(UserRejectedRequestError|UserRejectError|WalletRequestRejectedError)$/.test(name)) {
+            return true;
+        }
+        const message = String(candidate.message ?? '').trim();
+        if (/^(?:the )?user (?:rejected|declined|denied)(?: the)? (?:request|transaction|signature request|wallet request)[.!]?$/i.test(message)
+            || /^(?:request|transaction) (?:was )?(?:rejected|declined|denied) by (?:the )?user[.!]?$/i.test(message)) {
+            return true;
+        }
+        current = candidate.cause ?? candidate.error;
+    }
+    return false;
+}
+/**
+ * Normalize an adapter/host exception without retrying or resubmitting.
+ */
+function normalizeTransactionError(cause, errorMetadata = [], fallbackPhase = 'send') {
+    if (cause instanceof InstructionError) {
+        return cause;
+    }
+    const existingOutcome = getTransactionFailureOutcome(cause);
+    const instructionMatch = parseInstructionErrorMatch(cause, errorMetadata);
+    const asInstructionError = (programError) => {
+        const context = extractTransactionContext(cause);
+        const originalCause = existingOutcome?.cause ?? cause;
+        const outcome = {
+            status: 'chain-failed',
+            phase: existingOutcome?.status === 'chain-failed'
+                ? existingOutcome.phase
+                : 'chain',
+            signature: context.signature,
+            slot: context.slot,
+            programError,
+            cause: originalCause,
+        };
+        return new InstructionError(formatProgramError(programError), programError, originalCause, outcome);
+    };
+    if (instructionMatch?.deterministic) {
+        return asInstructionError(instructionMatch.programError);
+    }
+    if (existingOutcome) {
+        return cause instanceof TransactionExecutionError
+            ? cause
+            : new TransactionExecutionError(existingOutcome);
+    }
+    if (!existingOutcome && isWalletRejection(cause)) {
+        return new TransactionExecutionError({
+            status: 'not-submitted',
+            phase: 'wallet',
+            cause,
+        });
+    }
+    if (instructionMatch) {
+        return asInstructionError(instructionMatch.programError);
+    }
+    if (cause instanceof TransactionExecutionError) {
+        return cause;
+    }
+    if (existingOutcome) {
+        return new TransactionExecutionError(existingOutcome);
     }
+    const context = extractTransactionContext(cause);
+    if (context.signature) {
+        return new TransactionExecutionError({
+            status: 'submitted-unknown',
+            phase: 'confirmation',
+            signature: context.signature,
+            slot: context.slot,
+            cause,
+        });
+    }
+    return new TransactionExecutionError({
+        status: 'not-submitted',
+        phase: fallbackPhase,
+        cause,
+    });
 }
 
 /**
@@ -3076,9 +4893,24 @@ function buildInstruction(handler, params, options = {}) {
  * {@link InstructionError}.
  */
 async function executeInstruction(handler, params, options = {}) {
-    const instruction = buildInstruction(handler, params, options);
+    let instruction;
+    try {
+        instruction = buildInstruction(handler, params, options);
+    }
+    catch (cause) {
+        throw new TransactionExecutionError({
+            status: 'not-submitted',
+            phase: 'build',
+            cause,
+        });
+    }
     if (!options.wallet) {
-        throw new Error('Wallet required to sign and send transaction');
+        const cause = new Error('Wallet required to sign and send transaction');
+        throw new TransactionExecutionError({
+            status: 'not-submitted',
+            phase: 'wallet',
+            cause,
+        });
     }
     const sendOptions = {
         ...options.send,
@@ -3091,11 +4923,7 @@ async function executeInstruction(handler, params, options = {}) {
         return { signature: result.signature, slot: result.slot };
     }
     catch (err) {
-        const programError = parseInstructionError(err, handler.errors);
-        if (programError) {
-            throw new InstructionError(`${programError.name} (${programError.code}): ${programError.message}`, programError, err);
-        }
-        throw err;
+        throw normalizeTransactionError(err, handler.errors);
     }
 }
 /**
@@ -3199,6 +5027,7 @@ function mergeOperations(base, extension) {
 function extendProgram(program, extensions) {
     const base = program;
     const extended = { ...program };
+    delete extended.definitionHash;
     for (const key of ['pdas', 'accounts', 'queries', 'addresses', 'constants', 'defaults', 'math']) {
         const extensionValue = extensions[key];
         if (extensionValue !== undefined) {
@@ -3259,6 +5088,9 @@ function extendStack(stack, extensions) {
     if (baseRuntime || extensions.createRead || extensions.createFlows) {
         Object.defineProperty(extended, STACK_RUNTIME_EXTENSIONS, {
             value: {
+                readArgCounts: baseRuntime?.readArgCounts && extensions.readArgCounts
+                    ? mergeNamespace(baseRuntime.readArgCounts, extensions.readArgCounts)
+                    : extensions.readArgCounts ?? baseRuntime?.readArgCounts,
                 createRead: baseRuntime?.createRead && extensions.createRead
                     ? (client) => mergeNamespace(baseRuntime.createRead(client), extensions.createRead(client))
                     : extensions.createRead ?? baseRuntime?.createRead,
@@ -3467,19 +5299,69 @@ function validateTransactionSigners(transaction, host, options) {
         throw new Error(`Missing signer(s) for ${transaction.name}: ${missing.join(', ')}`);
     }
 }
+class OperationCallbackError extends Error {
+    constructor(input) {
+        super(`Operation '${input.operation.name}' ${input.phase} callback failed for transaction ${input.transactionIndex + 1} (${input.transaction.name})`);
+        this.name = 'OperationCallbackError';
+        this.phase = input.phase;
+        this.operation = input.operation;
+        this.transaction = input.transaction;
+        this.transactionIndex = input.transactionIndex;
+        this.receipt = input.receipt;
+        this.cause = input.cause;
+    }
+}
 class OperationExecutionError extends Error {
     constructor(input) {
-        super(`Operation '${input.operation.name}' failed at transaction ${input.failedTransactionIndex + 1} (${input.failedTransaction.name})`);
+        const context = `Operation '${input.operation.name}' failed at transaction ${input.failedTransactionIndex + 1} (${input.failedTransaction.name})`;
+        const detail = input.cause instanceof Error
+            ? input.cause.message
+            : typeof input.cause === 'string' ? input.cause : '';
+        super(detail ? `${context}: ${detail}` : context);
         this.name = 'OperationExecutionError';
         this.operation = input.operation;
         this.failedTransaction = input.failedTransaction;
         this.failedTransactionIndex = input.failedTransactionIndex;
         this.completedReceipts = [...input.completedReceipts];
+        this.callbackErrors = [...(input.callbackErrors ?? [])];
+        this.outcome = getTransactionFailureOutcome(input.cause) ?? input.outcome ?? {
+            status: 'not-submitted',
+            phase: 'send',
+            cause: input.cause,
+        };
+        this.signature = 'signature' in this.outcome ? this.outcome.signature : undefined;
+        this.slot = 'slot' in this.outcome ? this.outcome.slot : undefined;
         this.cause = input.cause;
     }
 }
+async function runOperationCallback(input, callbackErrors, onCallbackError) {
+    if (!input.callback) {
+        return;
+    }
+    try {
+        await input.callback();
+    }
+    catch (cause) {
+        const error = new OperationCallbackError({
+            phase: input.phase,
+            operation: input.operation,
+            transaction: input.transaction,
+            transactionIndex: input.transactionIndex,
+            receipt: input.receipt,
+            cause,
+        });
+        callbackErrors.push(error);
+        try {
+            await onCallbackError?.(error);
+        }
+        catch {
+            // The callback-error observer is also observational and must not alter execution.
+        }
+    }
+}
 async function executePreparedOperation(host, operation, options = {}) {
     const receipts = [];
+    const callbackErrors = [];
     const signers = [
         ...new Set([
             ...(options.signerRegistry?.values() ?? []),
@@ -3489,37 +5371,71 @@ async function executePreparedOperation(host, operation, options = {}) {
     for (const [transactionIndex, transaction] of operation.plan.transactions.entries()) {
         try {
             validateTransactionSigners(transaction, host, options);
-            await options.onTransactionStart?.({ operation, transaction, transactionIndex });
-            const result = await host.transaction(transaction.instructions, {
+        }
+        catch (cause) {
+            throw new OperationExecutionError({
+                operation,
+                failedTransaction: transaction,
+                failedTransactionIndex: transactionIndex,
+                completedReceipts: receipts,
+                callbackErrors,
+                outcome: {
+                    status: 'not-submitted',
+                    phase: 'build',
+                    cause,
+                },
+                cause,
+            });
+        }
+        const startEvent = { operation, transaction, transactionIndex };
+        await runOperationCallback({
+            phase: 'transaction-start',
+            ...startEvent,
+            callback: options.onTransactionStart
+                ? () => options.onTransactionStart(startEvent)
+                : undefined,
+        }, callbackErrors, options.onCallbackError);
+        let result;
+        try {
+            result = await host.transaction(transaction.instructions, {
                 wallet: options.wallet,
                 send: options.send,
                 errors: [...transaction.errors],
                 signers: signers.length > 0 ? signers : undefined,
-            });
-            const receipt = {
-                transactionIndex,
-                transactionName: transaction.name,
-                signature: result.signature,
-                slot: result.slot,
-            };
-            receipts.push(receipt);
-            await options.onTransactionSuccess?.({
-                operation,
-                transaction,
-                transactionIndex,
-                receipt,
+                transactionTransport: options.transactionTransport,
             });
         }
         catch (cause) {
+            const normalized = normalizeTransactionError(cause, transaction.errors);
             throw new OperationExecutionError({
                 operation,
                 failedTransaction: transaction,
                 failedTransactionIndex: transactionIndex,
                 completedReceipts: receipts,
-                cause,
+                callbackErrors,
+                outcome: getTransactionFailureOutcome(normalized) ?? undefined,
+                cause: normalized,
             });
         }
+        const receipt = {
+            transactionIndex,
+            transactionName: transaction.name,
+            signature: result.signature,
+            slot: result.slot,
+        };
+        receipts.push(receipt);
+        const successEvent = { operation, transaction, transactionIndex, receipt };
+        await runOperationCallback({
+            phase: 'transaction-success',
+            ...successEvent,
+            callback: options.onTransactionSuccess
+                ? () => options.onTransactionSuccess(successEvent)
+                : undefined,
+        }, callbackErrors, options.onCallbackError);
     }
+    const callbackErrorResult = callbackErrors.length > 0
+        ? { callbackErrors: [...callbackErrors] }
+        : {};
     if (operation.kind === 'flow') {
         return {
             kind: 'flow',
@@ -3527,6 +5443,7 @@ async function executePreparedOperation(host, operation, options = {}) {
             artifacts: operation.artifacts,
             signatures: nonEmpty(receipts.map((receipt) => receipt.signature), `Operation '${operation.name}' signatures`),
             transactions: nonEmpty(receipts, `Operation '${operation.name}' receipts`),
+            ...callbackErrorResult,
         };
     }
     return {
@@ -3535,8 +5452,25 @@ async function executePreparedOperation(host, operation, options = {}) {
         artifacts: operation.artifacts,
         signatures: [receipts[0].signature],
         transaction: receipts[0],
+        ...callbackErrorResult,
     };
 }
+/**
+ * Recursively unwrap operation context while retaining structured transaction outcomes.
+ */
+function unwrapOperationExecutionError(error) {
+    if (error instanceof InstructionError) {
+        return error;
+    }
+    if (error instanceof TransactionExecutionError) {
+        return error.outcome;
+    }
+    if (error instanceof OperationExecutionError) {
+        const underlying = unwrapOperationExecutionError(error.cause);
+        return underlying instanceof InstructionError ? underlying : error.outcome;
+    }
+    return error;
+}
 function convertToJsonValue(value, ancestors) {
     if (value === null || typeof value === 'string' || typeof value === 'boolean') {
         return value;
@@ -3619,6 +5553,31 @@ function describePreparedOperation(operation) {
         })),
     };
 }
+/**
+ * Inspect one prepared instruction/transaction without signing or submission.
+ * Multi-transaction flows are intentionally unsupported.
+ */
+async function inspectPreparedOperation(wallet, operation, options, context) {
+    if (operation.plan.transactions.length !== 1) {
+        throw new Error(`Cannot inspect operation '${operation.name}': multi-transaction operation inspection is not supported`);
+    }
+    if (operation.kind === 'flow') {
+        throw new Error(`Cannot inspect flow '${operation.name}': flow inspection is not supported`);
+    }
+    if (!wallet?.inspectTransaction) {
+        throw new Error('Wallet adapter does not support unsigned transaction inspection');
+    }
+    const transaction = operation.plan.transactions[0];
+    const description = describePreparedOperation(operation);
+    const inspection = context
+        ? await wallet.inspectTransaction(transaction.instructions, options, context)
+        : await wallet.inspectTransaction(transaction.instructions, options);
+    return {
+        description,
+        transaction: inspection,
+        programError: parseInstructionError(inspection.error ?? inspection, transaction.errors),
+    };
+}
 function formatPreparedOperation(operation) {
     const lines = [
         `${operation.kind}: ${operation.name}`,
@@ -3633,6 +5592,138 @@ function formatPreparedOperation(operation) {
     return lines.join('\n');
 }
 
+class TransactionTransportError extends Error {
+    constructor(status, body) {
+        super(body.message);
+        this.name = 'TransactionTransportError';
+        this.status = status;
+        this.code = body.code;
+        this.retryable = body.retryable;
+        this.requestId = body.request_id;
+        this.submissionState = body.submission_state;
+        this.signature = body.signature;
+        this.details = body.details;
+    }
+}
+function decimal(value) {
+    return value === undefined ? undefined : value.toString(10);
+}
+function bigintField(value, field) {
+    if (typeof value !== 'string' || !/^\d+$/.test(value)) {
+        throw new Error(`Invalid decimal u64 field '${field}' in transaction response`);
+    }
+    return BigInt(value);
+}
+function optionalBigint(value, field) {
+    return value === undefined || value === null ? undefined : bigintField(value, field);
+}
+function requestBody(value) {
+    return JSON.stringify(Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)));
+}
+async function parseError(response) {
+    let body = {};
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Public errors are deliberately synthesized without reflecting raw bodies.
+    }
+    return new TransactionTransportError(response.status, {
+        code: typeof body.code === 'string' ? body.code : 'transaction_transport_error',
+        message: typeof body.message === 'string' ? body.message : `Transaction request failed (${response.status})`,
+        retryable: body.retryable === true,
+        request_id: body.request_id ?? body.requestId,
+        submission_state: body.submission_state
+            ?? body.submissionState,
+        signature: body.signature,
+        details: body.details,
+    });
+}
+function createTransactionTransport(baseUrl, authenticatedFetch) {
+    const root = `${baseUrl.replace(/\/$/, '')}/transactions/v1`;
+    const post = async (route, body, scope) => {
+        const response = await authenticatedFetch(`${root}/${route}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: requestBody(body),
+        }, scope, true);
+        if (!response.ok)
+            throw await parseError(response);
+        return response.json();
+    };
+    return {
+        async getLatestBlockhash(options = {}) {
+            const value = await post('latest-blockhash', {
+                commitment: options.commitment,
+                minContextSlot: decimal(options.minContextSlot),
+            }, 'transaction:inspect');
+            return {
+                blockhash: String(value.blockhash),
+                contextSlot: bigintField(value.contextSlot, 'contextSlot'),
+                lastValidBlockHeight: bigintField(value.lastValidBlockHeight, 'lastValidBlockHeight'),
+            };
+        },
+        async getFeeForMessage(message, options = {}) {
+            const value = await post('fee', {
+                message,
+                commitment: options.commitment,
+                minContextSlot: decimal(options.minContextSlot),
+            }, 'transaction:inspect');
+            return {
+                feeLamports: value.feeLamports === null ? null : bigintField(value.feeLamports, 'feeLamports'),
+                contextSlot: bigintField(value.contextSlot, 'contextSlot'),
+            };
+        },
+        async simulateTransaction(transaction, options = {}) {
+            const value = await post('simulate', {
+                transaction,
+                commitment: options.commitment,
+                minContextSlot: decimal(options.minContextSlot),
+                accounts: options.accounts ? { addresses: options.accounts } : undefined,
+                innerInstructions: options.innerInstructions,
+                replaceRecentBlockhash: options.replaceRecentBlockhash,
+            }, 'transaction:inspect');
+            return {
+                contextSlot: bigintField(value.contextSlot, 'contextSlot'),
+                err: value.err ?? null,
+                logs: value.logs ?? null,
+                unitsConsumed: optionalBigint(value.unitsConsumed, 'unitsConsumed'),
+                accounts: value.accounts,
+            };
+        },
+        sendTransaction(transaction, options = {}) {
+            return post('send', {
+                transaction,
+                skipPreflight: options.skipPreflight,
+                preflightCommitment: options.preflightCommitment,
+                minContextSlot: decimal(options.minContextSlot),
+            }, 'transaction:send');
+        },
+        async getSignatureStatus(signature, options = {}) {
+            const value = await post('signature-status', {
+                signature,
+                searchTransactionHistory: options.searchTransactionHistory,
+            }, 'transaction:inspect');
+            const status = value?.status;
+            if (!status)
+                return null;
+            return {
+                signature,
+                slot: status.slot === null ? null : bigintField(status.slot, 'slot'),
+                confirmationStatus: status.confirmationStatus,
+                err: status.err ?? null,
+            };
+        },
+        async getBlockHeight(options = {}) {
+            const value = await post('block-height', {
+                commitment: options.commitment,
+                minContextSlot: decimal(options.minContextSlot),
+            }, 'transaction:inspect');
+            return bigintField(value.blockHeight, 'blockHeight');
+        },
+    };
+}
+
 function mergeAttachedPrograms(stack, attachedPrograms) {
     const merged = { ...(attachedPrograms ?? {}) };
     for (const [name, definition] of Object.entries(stack.programs ?? {})) {
@@ -3678,6 +5769,29 @@ function cloneStackWithPrograms(stack, programs) {
 function withPrograms(stack, attachedPrograms) {
     return cloneStackWithPrograms(stack, mergeAttachedPrograms(stack, attachedPrograms));
 }
+function composeExecutionCallbacks(defaultCallback, callCallback) {
+    if (!defaultCallback) {
+        return callCallback
+            ? async (value) => { await callCallback(value); }
+            : undefined;
+    }
+    if (!callCallback) {
+        return async (value) => { await defaultCallback(value); };
+    }
+    return async (value) => {
+        const errors = [];
+        for (const callback of [defaultCallback, callCallback]) {
+            try {
+                await callback(value);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0)
+            throw errors[0];
+    };
+}
 let Arete$1 = class Arete {
     constructor(url, httpBaseUrl, options) {
         this.stack = options.stack;
@@ -3686,25 +5800,38 @@ let Arete$1 = class Arete {
         this.httpBaseUrl = httpBaseUrl;
         this.fetchImpl = options.fetch ?? this.resolveFetchImpl();
         this.storage = new SortedStorageDecorator(options.storage ?? new MemoryAdapter());
+        this.queryStore = new QueryStore(this.storage);
         this.processor = new FrameProcessor(this.storage, {
             maxEntriesPerView: options.maxEntriesPerView,
             flushIntervalMs: options.flushIntervalMs,
             schemas: this.stack.schemas,
             patchSchemas: this.stack.patchSchemas,
+            queryStore: this.queryStore,
+            warnOnValidationError: options.validateFrames !== false,
+            onValidationError: options.onFrameValidationError,
         });
         this.connection = new ConnectionManager({
             websocketUrl: url,
+            autoReconnect: options.autoReconnect,
             reconnectIntervals: options.reconnectIntervals,
             maxReconnectAttempts: options.maxReconnectAttempts,
             auth: options.auth,
         });
-        this.subscriptionRegistry = new SubscriptionRegistry(this.connection);
+        this.subscriptionRegistry = new SubscriptionRegistry(this.connection, this.queryStore);
         this.connection.onFrame((frame) => {
             this.processor.handleFrame(frame);
         });
+        this.connection.onStateChange((state) => {
+            this.subscriptionRegistry.handleConnectionState(state);
+        });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
         this._queries = this.buildQueries();
-        this._chain = createChainClient(this.httpBaseUrl, this.authenticatedFetch.bind(this));
+        this._chain = createChainClient(this.httpBaseUrl, ((input, init) => this.authenticatedFetch(typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url, init, ['read'])));
+        this._transactions = createTransactionTransport(this.httpBaseUrl, (input, init, scope, requirePreDispatchMarker) => this.authenticatedFetch(input, init, [scope], requirePreDispatchMarker));
         this._programs = this.buildPrograms();
     }
     resolveFetchImpl() {
@@ -3819,12 +5946,12 @@ let Arete$1 = class Arete {
             method: options?.method ?? 'GET',
             headers: options?.body === undefined ? undefined : { 'content-type': 'application/json' },
             body: options?.body === undefined ? undefined : JSON.stringify(options.body),
-        });
+        }, ['read']);
         return parseReadResponse(response, path);
     }
-    async authenticatedFetch(input, init) {
+    async authenticatedFetch(input, init, requiredScopes = ['read'], requirePreDispatchMarker = false) {
         const attempt = async (forceRefresh = false) => {
-            const token = await this.connection.getHttpAuthToken(forceRefresh);
+            const token = await this.connection.getHttpAuthToken(requiredScopes, forceRefresh);
             const headers = new Headers(init?.headers ?? undefined);
             if (token) {
                 headers.set('authorization', `Bearer ${token}`);
@@ -3838,7 +5965,10 @@ let Arete$1 = class Arete {
         if (!response.ok) {
             const wireErrorCode = response.headers.get('X-Error-Code');
             const errorCode = wireErrorCode ? parseErrorCode(wireErrorCode) : undefined;
-            if (errorCode && shouldRefreshToken(errorCode)) {
+            const explicitlyNotDispatched = response.headers.get('X-Arete-Upstream-Attempted') === 'false';
+            if (errorCode
+                && shouldRefreshToken(errorCode)
+                && (!requirePreDispatchMarker || explicitlyNotDispatched)) {
                 this.connection.clearHttpAuthToken();
                 response = await attempt(true);
             }
@@ -3858,8 +5988,8 @@ let Arete$1 = class Arete {
     }
     static async connect(stack, options) {
         const requestedUrl = options?.url ?? stack.endpoints.ws;
-        const autoReconnect = options?.autoReconnect !== false;
-        const httpOnly = options?.transport === 'http' || (!requestedUrl && !autoReconnect);
+        const autoConnect = options?.autoConnect !== false;
+        const httpOnly = options?.transport === 'http';
         const url = httpOnly ? null : requestedUrl;
         const httpUrl = options?.httpUrl
             ?? stack.endpoints.http
@@ -3878,17 +6008,19 @@ let Arete$1 = class Arete {
             storage: options?.storage,
             maxEntriesPerView: options?.maxEntriesPerView,
             flushIntervalMs: options?.flushIntervalMs,
+            autoConnect: options?.autoConnect,
             autoReconnect: options?.autoReconnect,
             reconnectIntervals: options?.reconnectIntervals,
             maxReconnectAttempts: options?.maxReconnectAttempts,
             validateFrames: options?.validateFrames,
+            onFrameValidationError: options?.onFrameValidationError,
             auth: options?.auth,
             wallet: options?.wallet,
             fetch: options?.fetch,
             execution: options?.execution,
         };
         const client = new Arete(url, httpUrl, internalOptions);
-        if (!httpOnly && autoReconnect) {
+        if (!httpOnly && autoConnect) {
             await client.connection.connect();
         }
         return applyConnectedStackExtensions(client, effectiveStack);
@@ -3905,6 +6037,9 @@ let Arete$1 = class Arete {
     get chain() {
         return this._chain;
     }
+    get transactions() {
+        return this._transactions;
+    }
     /** The default wallet adapter, if one was configured. */
     get wallet() {
         return this._wallet;
@@ -3935,7 +6070,12 @@ let Arete$1 = class Arete {
     async transaction(instructions, options) {
         const wallet = options?.wallet ?? this._wallet;
         if (!wallet) {
-            throw new Error('Wallet required to sign and send transaction');
+            const cause = new Error('Wallet required to sign and send transaction');
+            throw new TransactionExecutionError({
+                status: 'not-submitted',
+                phase: 'wallet',
+                cause,
+            });
         }
         try {
             const sendOptions = {
@@ -3944,15 +6084,13 @@ let Arete$1 = class Arete {
             if (options?.signers !== undefined) {
                 sendOptions.signers = options.signers;
             }
-            const result = await wallet.signAndSend(instructions, sendOptions);
+            const result = await wallet.signAndSend(instructions, sendOptions, {
+                transactionTransport: options?.transactionTransport ?? this._transactions,
+            });
             return { signature: result.signature, slot: result.slot };
         }
         catch (err) {
-            const programError = parseInstructionError(err, options?.errors ?? this.aggregateErrors());
-            if (programError) {
-                throw new InstructionError(`${programError.name} (${programError.code}): ${programError.message}`, programError, err);
-            }
-            throw err;
+            throw normalizeTransactionError(err, options?.errors ?? this.aggregateErrors());
         }
     }
     execute(prepared, options) {
@@ -3963,12 +6101,18 @@ let Arete$1 = class Arete {
                 ? { ...(defaults?.send ?? {}), ...(options?.send ?? {}) }
                 : undefined,
             signers: options?.signers ?? defaults?.signers,
+            transactionTransport: options?.transactionTransport ?? defaults?.transactionTransport,
             signerRegistry: options?.signerRegistry ?? defaults?.signerRegistry,
             availableSignerAddresses: options?.availableSignerAddresses ?? defaults?.availableSignerAddresses,
-            onTransactionStart: options?.onTransactionStart ?? defaults?.onTransactionStart,
-            onTransactionSuccess: options?.onTransactionSuccess ?? defaults?.onTransactionSuccess,
+            onTransactionStart: composeExecutionCallbacks(defaults?.onTransactionStart, options?.onTransactionStart),
+            onTransactionSuccess: composeExecutionCallbacks(defaults?.onTransactionSuccess, options?.onTransactionSuccess),
+            onCallbackError: composeExecutionCallbacks(defaults?.onCallbackError, options?.onCallbackError),
         });
     }
+    /** Inspect one prepared instruction/transaction without signing or submitting it. */
+    inspectOperation(prepared, options) {
+        return inspectPreparedOperation(options?.wallet ?? this._wallet, prepared, options?.inspect, { transactionTransport: options?.transactionTransport ?? this._transactions });
+    }
     /** Error metadata from every handler in the stack, deduped by code. */
     aggregateErrors() {
         if (!this._aggregatedErrors) {
@@ -4000,6 +6144,17 @@ let Arete$1 = class Arete {
     get store() {
         return this.storage;
     }
+    /** Highest Solana slot whose streamed frame has been stored locally. */
+    get processedSlot() {
+        return this.processor.getProcessedSlot();
+    }
+    /**
+     * Wait until a frame at or beyond `slot` has been applied to local storage.
+     * Buffered frames satisfy the wait only after their storage batch is flushed.
+     */
+    waitForProcessedSlot(slot, options) {
+        return this.processor.waitForProcessedSlot(slot, options);
+    }
     onConnectionStateChange(callback) {
         return this.connection.onStateChange(callback);
     }
@@ -4031,6 +6186,9 @@ let Arete$1 = class Arete {
     getSubscriptionRegistry() {
         return this.subscriptionRegistry;
     }
+    getQueryStore() {
+        return this.queryStore;
+    }
 };
 
 function createSignerRegistry(entries = []) {
@@ -4084,6 +6242,7 @@ function resolveMemberConnectOptions(stack, member, options, forceHttpOnly) {
         transport,
         auth: member?.auth ?? options?.auth,
         storage: member?.storage,
+        autoConnect: member?.autoConnect,
         autoReconnect: member?.autoReconnect,
         wallet: options?.wallet,
         fetch: options?.fetch,
@@ -4123,6 +6282,7 @@ async function createSession(definition, options) {
         ...connectedPrograms.map(([, client]) => client),
     ];
     const executionHost = memberClients[0];
+    const transactions = options?.transactions ?? executionHost.transactions;
     const stacks = Object.fromEntries(connectedStacks);
     const explicitProgramKeys = new Set(connectedPrograms.map(([key]) => key));
     const programOwners = new Map();
@@ -4160,12 +6320,14 @@ async function createSession(definition, options) {
         },
         signerRegistry,
         chain,
+        transactions,
         transaction(instructions, transactionOptions) {
             const defaults = options?.execution;
             const configuredSigners = transactionOptions?.signers ?? defaults?.signers;
             const signers = [...new Set([...signerRegistry.values(), ...(configuredSigners ?? [])])];
             return executionHost.transaction(instructions, {
                 wallet: transactionOptions?.wallet ?? defaults?.wallet,
+                transactionTransport: transactionOptions?.transactionTransport ?? transactions,
                 send: defaults?.send || transactionOptions?.send
                     ? { ...(defaults?.send ?? {}), ...(transactionOptions?.send ?? {}) }
                     : undefined,
@@ -4178,6 +6340,7 @@ async function createSession(definition, options) {
             const configuredSigners = executionOptions?.signers ?? defaults?.signers;
             return executionHost.execute(prepared, {
                 wallet: executionOptions?.wallet ?? defaults?.wallet,
+                transactionTransport: executionOptions?.transactionTransport ?? defaults?.transactionTransport ?? transactions,
                 send: defaults?.send || executionOptions?.send
                     ? { ...(defaults?.send ?? {}), ...(executionOptions?.send ?? {}) }
                     : undefined,
@@ -4186,6 +6349,7 @@ async function createSession(definition, options) {
                 availableSignerAddresses: executionOptions?.availableSignerAddresses ?? defaults?.availableSignerAddresses,
                 onTransactionStart: executionOptions?.onTransactionStart ?? defaults?.onTransactionStart,
                 onTransactionSuccess: executionOptions?.onTransactionSuccess ?? defaults?.onTransactionSuccess,
+                onCallbackError: executionOptions?.onCallbackError ?? defaults?.onCallbackError,
             });
         },
         setWallet(nextWallet) {
@@ -4301,6 +6465,15 @@ function toRawAmount(amount, decimals) {
     }
     return parseUiAmountToRaw(amount.ui, decimals);
 }
+/** Convert an amount to raw units without throwing on invalid user input. */
+function safeToRawAmount(amount, decimals) {
+    try {
+        return { success: true, data: toRawAmount(amount, decimals) };
+    }
+    catch (error) {
+        return { success: false, error };
+    }
+}
 /** Fetch a mint's decimals via the chain read endpoint, throwing when unavailable. */
 async function getMintDecimals(chain, mint) {
     const account = await chain.mint(mint);
@@ -4349,7 +6522,28 @@ async function resolveAmountsToRaw(chain, inputs) {
     return Object.fromEntries(entries);
 }
 
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function stringifyBigints(value) {
+    if (typeof value === 'bigint') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => stringifyBigints(entry));
+    }
+    if (value !== null && typeof value === 'object' && isPlainObject(value)) {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            out[key] = stringifyBigints(entry);
+        }
+        return out;
+    }
+    return value;
+}
+
 const Arete = Object.assign(Arete$1, { session: createSession });
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, instructionOperation, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, literal, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, serializeInstructionData, stackQuery, toJsonValue, toRawAmount, transactionOperation, validateAccountResolution, withPrograms };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TransactionExecutionError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, safeToRawAmount, serializeInstructionData, serializeViewKey, stackQuery, stringifyBigints, toJsonValue, toRawAmount, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateSubscriptionId, withPrograms };
 //# sourceMappingURL=index.esm.js.map