@usearete/sdk 0.2.0 → 0.3.0

package/dist/{index.js → index.cjs}

@@ -1,10 +1,11 @@
 'use strict';
 
 var pako = require('pako');
-var ed25519 = require('@noble/ed25519');
+var buffer = require('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,
@@ -69,51 +70,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 = pako.inflate(bytes);
-        const jsonString = new TextDecoder().decode(decompressed);
-        return JSON.parse(jsonString);
+    const decoded = isGzipData(bytes) ? pako.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;
@@ -175,14 +566,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;
@@ -201,24 +593,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() {
@@ -248,7 +648,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');
@@ -256,6 +656,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');
         }
@@ -264,23 +665,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) {
@@ -290,7 +733,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) {
@@ -299,15 +744,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: {
@@ -318,7 +765,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();
@@ -383,10 +830,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 &&
@@ -398,16 +846,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) {
@@ -453,6 +908,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');
@@ -492,8 +952,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();
@@ -518,49 +984,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();
@@ -569,7 +1061,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) {
@@ -585,7 +1079,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));
@@ -593,21 +1097,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;
@@ -616,13 +1127,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;
@@ -638,8 +1153,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;
@@ -655,85 +1174,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) {
@@ -746,6 +1322,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;
@@ -755,8 +1335,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);
     }
@@ -783,6 +1367,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);
 }
@@ -850,6 +1442,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
@@ -857,6 +1451,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;
@@ -868,20 +1465,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;
@@ -937,8 +1558,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, {
@@ -968,6 +1600,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.
      */
@@ -994,31 +1665,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;
         }
@@ -1026,17 +1781,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);
@@ -1044,12 +1802,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, {
@@ -1059,6 +1823,7 @@ class FrameProcessor {
             });
             this.emitRichUpdate(viewPath, entity.key, previousValue, nextValue, 'upsert');
         }
+        this.queryStore?.stageSnapshot(frame, acceptedKeys);
     }
     handleEntityFrame(frame) {
         this.handleEntityFrameWithoutEnforce(frame);
@@ -1067,44 +1832,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, {
@@ -1115,6 +1922,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;
         }
     }
@@ -1124,13 +1932,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);
         }
     }
 }
@@ -1277,7 +2092,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)
@@ -1433,7 +2248,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;
@@ -1441,7 +2256,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;
@@ -1464,8 +2279,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;
@@ -1478,303 +2293,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;
         },
     };
 }
@@ -1871,7 +2967,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 {
@@ -1902,6 +3029,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));
@@ -1938,18 +3078,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.
  *
@@ -2135,7 +3726,7 @@ function isOnCurve(publicKey) {
         return false;
     }
     try {
-        ed25519.Point.fromHex(publicKey);
+        Point.fromHex(publicKey);
         return true;
     }
     catch {
@@ -2651,7 +4242,7 @@ function validateAccountResolution(result) {
  * @returns Serialized instruction data
  */
 function serializeInstructionData(discriminator, args, schema) {
-    const buffers = [Buffer.from(discriminator)];
+    const buffers = [buffer.Buffer.from(discriminator)];
     for (const field of schema) {
         const value = args[field.name];
         // Option fields treat undefined as None; everything else must be present
@@ -2662,7 +4253,7 @@ function serializeInstructionData(discriminator, args, schema) {
         const serialized = serializeValue(value, field.type);
         buffers.push(serialized);
     }
-    return Buffer.concat(buffers);
+    return buffer.Buffer.concat(buffers);
 }
 function serializeValue(value, type) {
     if (typeof type === 'string') {
@@ -2702,7 +4293,7 @@ function serializeStruct(value, fields) {
         }
         buffers.push(serializeValue(fieldValue, field.type));
     }
-    return Buffer.concat(buffers);
+    return buffer.Buffer.concat(buffers);
 }
 function serializeHashMap(value, keyType, valueType) {
     if (keyType !== 'string') {
@@ -2713,15 +4304,15 @@ function serializeHashMap(value, keyType, valueType) {
     }
     const entries = Object.entries(value).sort(([left], [right]) => 
     // Rust/Borsh sorts String keys by their UTF-8 bytes before serializing.
-    Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8')));
-    const len = Buffer.alloc(4);
+    buffer.Buffer.compare(buffer.Buffer.from(left, 'utf8'), buffer.Buffer.from(right, 'utf8')));
+    const len = buffer.Buffer.alloc(4);
     len.writeUInt32LE(entries.length, 0);
     const entryBuffers = [];
     for (const [key, entryValue] of entries) {
         entryBuffers.push(serializePrimitive(key, 'string'));
         entryBuffers.push(serializeValue(entryValue, valueType));
     }
-    return Buffer.concat([len, ...entryBuffers]);
+    return buffer.Buffer.concat([len, ...entryBuffers]);
 }
 function variantName(variant) {
     return typeof variant === 'string' ? variant : variant.name;
@@ -2736,7 +4327,7 @@ function serializeEnum(value, variants) {
         if (typeof variant !== 'string') {
             throw new Error(`Enum variant "${variantName(variant)}" carries data; pass { ${variantName(variant)}: ... } instead of an index`);
         }
-        return Buffer.from([value]);
+        return buffer.Buffer.from([value]);
     }
     // String value: a fieldless variant by name.
     if (typeof value === 'string') {
@@ -2748,7 +4339,7 @@ function serializeEnum(value, variants) {
         if (typeof variant !== 'string') {
             throw new Error(`Enum variant "${value}" carries data; pass { ${value}: ... } instead of a bare name`);
         }
-        return Buffer.from([index]);
+        return buffer.Buffer.from([index]);
     }
     // Object value: { variantName: payload } for data-carrying variants.
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
@@ -2766,58 +4357,58 @@ function serializeEnum(value, variants) {
         if (typeof variant === 'string') {
             throw new Error(`Enum variant "${key}" is fieldless; pass '${key}' instead of an object`);
         }
-        const prefix = Buffer.from([index]);
+        const prefix = buffer.Buffer.from([index]);
         if ('fields' in variant) {
-            return Buffer.concat([prefix, serializeStruct(payload, variant.fields)]);
+            return buffer.Buffer.concat([prefix, serializeStruct(payload, variant.fields)]);
         }
         const tuple = payload;
         if (!Array.isArray(tuple) || tuple.length !== variant.tuple.length) {
             throw new Error(`Enum variant "${key}" expects a tuple of length ${variant.tuple.length}`);
         }
         const elements = variant.tuple.map((elementType, i) => serializeValue(tuple[i], elementType));
-        return Buffer.concat([prefix, ...elements]);
+        return buffer.Buffer.concat([prefix, ...elements]);
     }
     throw new Error(`Cannot serialize enum from value of type ${typeof value}`);
 }
 function serializePrimitive(value, type) {
     switch (type) {
         case 'u8':
-            return Buffer.from([value]);
+            return buffer.Buffer.from([value]);
         case 'u16':
-            const u16 = Buffer.alloc(2);
+            const u16 = buffer.Buffer.alloc(2);
             u16.writeUInt16LE(value, 0);
             return u16;
         case 'u32':
-            const u32 = Buffer.alloc(4);
+            const u32 = buffer.Buffer.alloc(4);
             u32.writeUInt32LE(value, 0);
             return u32;
         case 'u64':
-            const u64 = Buffer.alloc(8);
+            const u64 = buffer.Buffer.alloc(8);
             u64.writeBigUInt64LE(BigInt(value), 0);
             return u64;
         case 'u128':
             // u128 is 16 bytes, little-endian
-            const u128 = Buffer.alloc(16);
+            const u128 = buffer.Buffer.alloc(16);
             const bigU128 = BigInt(value);
             u128.writeBigUInt64LE(bigU128 & BigInt('0xFFFFFFFFFFFFFFFF'), 0);
             u128.writeBigUInt64LE(bigU128 >> BigInt(64), 8);
             return u128;
         case 'i8':
-            return Buffer.from([value]);
+            return buffer.Buffer.from([value]);
         case 'i16':
-            const i16 = Buffer.alloc(2);
+            const i16 = buffer.Buffer.alloc(2);
             i16.writeInt16LE(value, 0);
             return i16;
         case 'i32':
-            const i32 = Buffer.alloc(4);
+            const i32 = buffer.Buffer.alloc(4);
             i32.writeInt32LE(value, 0);
             return i32;
         case 'i64':
-            const i64 = Buffer.alloc(8);
+            const i64 = buffer.Buffer.alloc(8);
             i64.writeBigInt64LE(BigInt(value), 0);
             return i64;
         case 'i128':
-            const i128 = Buffer.alloc(16);
+            const i128 = buffer.Buffer.alloc(16);
             const bigI128 = BigInt(value);
             // The masked low limb is always non-negative, so it must be written
             // unsigned; the arithmetic-shifted high limb carries the sign.
@@ -2825,17 +4416,17 @@ function serializePrimitive(value, type) {
             i128.writeBigInt64LE(bigI128 >> BigInt(64), 8);
             return i128;
         case 'f32': {
-            const f32 = Buffer.alloc(4);
+            const f32 = buffer.Buffer.alloc(4);
             f32.writeFloatLE(value, 0);
             return f32;
         }
         case 'f64': {
-            const f64 = Buffer.alloc(8);
+            const f64 = buffer.Buffer.alloc(8);
             f64.writeDoubleLE(value, 0);
             return f64;
         }
         case 'bool':
-            return Buffer.from([value ? 1 : 0]);
+            return buffer.Buffer.from([value ? 1 : 0]);
         case 'bytes': {
             // Borsh bytes: u32 LE length prefix + raw bytes.
             const raw = value instanceof Uint8Array
@@ -2846,30 +4437,30 @@ function serializePrimitive(value, type) {
             if (raw === null) {
                 throw new Error(`Cannot serialize bytes from value of type ${typeof value}`);
             }
-            const lenPrefix = Buffer.alloc(4);
+            const lenPrefix = buffer.Buffer.alloc(4);
             lenPrefix.writeUInt32LE(raw.length, 0);
-            return Buffer.concat([lenPrefix, Buffer.from(raw)]);
+            return buffer.Buffer.concat([lenPrefix, buffer.Buffer.from(raw)]);
         }
         case 'string':
             const str = value;
-            const strBytes = Buffer.from(str, 'utf-8');
-            const strLen = Buffer.alloc(4);
+            const strBytes = buffer.Buffer.from(str, 'utf-8');
+            const strLen = buffer.Buffer.alloc(4);
             strLen.writeUInt32LE(strBytes.length, 0);
-            return Buffer.concat([strLen, strBytes]);
+            return buffer.Buffer.concat([strLen, strBytes]);
         case 'pubkey': {
             // Public key is 32 bytes. Accept base58 strings or raw 32-byte buffers.
             if (value instanceof Uint8Array) {
                 if (value.length !== 32) {
                     throw new Error(`Invalid pubkey byte length: expected 32, got ${value.length}`);
                 }
-                return Buffer.from(value);
+                return buffer.Buffer.from(value);
             }
             if (typeof value === 'string') {
                 const decoded = decodeBase58(value);
                 if (decoded.length !== 32) {
                     throw new Error(`Invalid pubkey: '${value}' decoded to ${decoded.length} bytes, expected 32`);
                 }
-                return Buffer.from(decoded);
+                return buffer.Buffer.from(decoded);
             }
             throw new Error(`Cannot serialize pubkey from value of type ${typeof value}`);
         }
@@ -2878,29 +4469,42 @@ function serializePrimitive(value, type) {
     }
 }
 function serializeVec(values, elementType) {
-    const len = Buffer.alloc(4);
+    const len = buffer.Buffer.alloc(4);
     len.writeUInt32LE(values.length, 0);
     const elementBuffers = values.map(v => serializeValue(v, elementType));
-    return Buffer.concat([len, ...elementBuffers]);
+    return buffer.Buffer.concat([len, ...elementBuffers]);
 }
 function serializeOption(value, innerType) {
     if (value === null || value === undefined) {
-        return Buffer.from([0]); // None
+        return buffer.Buffer.from([0]); // None
     }
     const inner = serializeValue(value, innerType);
-    return Buffer.concat([Buffer.from([1]), inner]); // Some
+    return buffer.Buffer.concat([buffer.Buffer.from([1]), inner]); // Some
 }
 function serializeArray(values, elementType, length) {
     if (values.length !== length) {
         throw new Error(`Array length mismatch: expected ${length}, got ${values.length}`);
     }
     const elementBuffers = values.map(v => serializeValue(v, elementType));
-    return Buffer.concat(elementBuffers);
+    return buffer.Buffer.concat(elementBuffers);
 }
 
 /**
  * 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.
  *
@@ -2909,44 +4513,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.
@@ -2962,12 +4606,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,
+    });
 }
 
 /**
@@ -3078,9 +4895,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,
@@ -3093,11 +4925,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);
     }
 }
 /**
@@ -3201,6 +5029,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) {
@@ -3261,6 +5090,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,
@@ -3469,19 +5301,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() ?? []),
@@ -3491,37 +5373,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',
@@ -3529,6 +5445,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 {
@@ -3537,8 +5454,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;
@@ -3621,6 +5555,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}`,
@@ -3635,6 +5594,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 ?? {})) {
@@ -3680,6 +5771,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;
@@ -3688,25 +5802,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() {
@@ -3821,12 +5948,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}`);
@@ -3840,7 +5967,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);
             }
@@ -3860,8 +5990,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
@@ -3880,17 +6010,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);
@@ -3907,6 +6039,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;
@@ -3937,7 +6072,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 = {
@@ -3946,15 +6086,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) {
@@ -3965,12 +6103,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) {
@@ -4002,6 +6146,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);
     }
@@ -4033,6 +6188,9 @@ let Arete$1 = class Arete {
     getSubscriptionRegistry() {
         return this.subscriptionRegistry;
     }
+    getQueryStore() {
+        return this.queryStore;
+    }
 };
 
 function createSignerRegistry(entries = []) {
@@ -4086,6 +6244,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,
@@ -4125,6 +6284,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();
@@ -4162,12 +6322,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,
@@ -4180,6 +6342,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,
@@ -4188,6 +6351,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) {
@@ -4303,6 +6467,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);
@@ -4351,6 +6524,27 @@ 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 });
 
 exports.ASSOCIATED_TOKEN_PROGRAM_ADDRESS = ASSOCIATED_TOKEN_PROGRAM_ADDRESS;
@@ -4362,14 +6556,19 @@ exports.DEFAULT_MAX_ENTRIES_PER_VIEW = DEFAULT_MAX_ENTRIES_PER_VIEW;
 exports.FrameProcessor = FrameProcessor;
 exports.InstructionError = InstructionError;
 exports.MemoryAdapter = MemoryAdapter;
+exports.OperationCallbackError = OperationCallbackError;
 exports.OperationExecutionError = OperationExecutionError;
 exports.PROGRAM_OPERATION_EXTENSIONS = PROGRAM_OPERATION_EXTENSIONS;
+exports.ProcessedSlotTimeoutError = ProcessedSlotTimeoutError;
+exports.QueryStore = QueryStore;
 exports.ReadRequestError = ReadRequestError;
 exports.SPL_TOKEN_PROGRAM_ADDRESS = SPL_TOKEN_PROGRAM_ADDRESS;
 exports.STACK_RUNTIME_EXTENSIONS = STACK_RUNTIME_EXTENSIONS;
 exports.SYSTEM_PROGRAM_ADDRESS = SYSTEM_PROGRAM_ADDRESS;
 exports.SubscriptionRegistry = SubscriptionRegistry;
 exports.TOKEN_2022_PROGRAM_ADDRESS = TOKEN_2022_PROGRAM_ADDRESS;
+exports.TransactionExecutionError = TransactionExecutionError;
+exports.TransactionTransportError = TransactionTransportError;
 exports.account = account;
 exports.appendFlowTransactions = appendFlowTransactions;
 exports.appendTransactionInstructions = appendTransactionInstructions;
@@ -4377,6 +6576,7 @@ exports.applyConnectedStackExtensions = applyConnectedStackExtensions;
 exports.arg = arg;
 exports.buildInstruction = buildInstruction;
 exports.bytes = bytes;
+exports.canonicalQueryKey = canonicalQueryKey;
 exports.chainAccountLoader = chainAccountLoader;
 exports.createChainClient = createChainClient;
 exports.createEntityStream = createEntityStream;
@@ -4392,6 +6592,8 @@ exports.createRichUpdateStream = createRichUpdateStream;
 exports.createSeed = createSeed;
 exports.createSession = createSession;
 exports.createSignerRegistry = createSignerRegistry;
+exports.createSubscriptionId = createSubscriptionId;
+exports.createTransactionTransport = createTransactionTransport;
 exports.createTypedListView = createTypedListView;
 exports.createTypedStateView = createTypedStateView;
 exports.createTypedViews = createTypedViews;
@@ -4418,12 +6620,21 @@ exports.formatRawToUi = formatRawToUi;
 exports.getMintDecimals = getMintDecimals;
 exports.getProgramRuntimeExtensions = getProgramRuntimeExtensions;
 exports.getStackRuntimeExtensions = getStackRuntimeExtensions;
+exports.getTransactionFailureOutcome = getTransactionFailureOutcome;
+exports.inspectPreparedOperation = inspectPreparedOperation;
 exports.instructionOperation = instructionOperation;
 exports.isEntityFrame = isEntityFrame;
+exports.isErrorFrame = isErrorFrame;
+exports.isHostedAreteEndpoint = isHostedAreteEndpoint;
 exports.isSnapshotFrame = isSnapshotFrame;
 exports.isSubscribedFrame = isSubscribedFrame;
+exports.isUnsubscribedFrame = isUnsubscribedFrame;
 exports.isValidFrame = isValidFrame;
 exports.literal = literal;
+exports.normalizeSubscription = normalizeSubscription;
+exports.normalizeSubscriptionQuery = normalizeSubscriptionQuery;
+exports.normalizeSubscriptionRequest = normalizeSubscriptionRequest;
+exports.normalizeTransactionError = normalizeTransactionError;
 exports.parseFrame = parseFrame;
 exports.parseFrameFromBlob = parseFrameFromBlob;
 exports.parseInstructionError = parseInstructionError;
@@ -4438,11 +6649,16 @@ exports.resolveAmount = resolveAmount;
 exports.resolveAmountToRaw = resolveAmountToRaw;
 exports.resolveAmountsToRaw = resolveAmountsToRaw;
 exports.resolveTokenProgramAddress = resolveTokenProgramAddress;
+exports.safeToRawAmount = safeToRawAmount;
 exports.serializeInstructionData = serializeInstructionData;
+exports.serializeViewKey = serializeViewKey;
 exports.stackQuery = stackQuery;
+exports.stringifyBigints = stringifyBigints;
 exports.toJsonValue = toJsonValue;
 exports.toRawAmount = toRawAmount;
 exports.transactionOperation = transactionOperation;
+exports.unwrapOperationExecutionError = unwrapOperationExecutionError;
 exports.validateAccountResolution = validateAccountResolution;
+exports.validateSubscriptionId = validateSubscriptionId;
 exports.withPrograms = withPrograms;
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map