@usearete/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,78 @@
+import { Buffer } from 'buffer';
+
+type TransactionCommitment = 'processed' | 'confirmed' | 'finalized';
+type TransactionAuthScope = 'transaction:inspect' | 'transaction:send';
+interface TransactionRequestContext {
+    commitment?: TransactionCommitment;
+    minContextSlot?: bigint;
+}
+interface LatestBlockhashResult {
+    blockhash: string;
+    contextSlot: bigint;
+    lastValidBlockHeight: bigint;
+}
+interface TransactionFeeResult {
+    feeLamports: bigint | null;
+    contextSlot: bigint;
+}
+interface TransactionSimulationOptions extends TransactionRequestContext {
+    accounts?: readonly string[];
+    innerInstructions?: boolean;
+    replaceRecentBlockhash?: boolean;
+}
+interface TransactionSimulationResult {
+    contextSlot: bigint;
+    err: unknown | null;
+    logs: readonly string[] | null;
+    unitsConsumed?: bigint;
+    accounts?: readonly unknown[] | null;
+}
+interface TransactionSendOptions {
+    skipPreflight?: boolean;
+    preflightCommitment?: TransactionCommitment;
+    minContextSlot?: bigint;
+}
+interface TransactionSendResult {
+    signature: string;
+}
+interface TransactionSignatureStatus {
+    signature: string;
+    slot: bigint | null;
+    confirmationStatus: TransactionCommitment | null;
+    err: unknown | null;
+}
+interface TransactionTransportErrorBody {
+    code: string;
+    message: string;
+    retryable: boolean;
+    request_id?: string;
+    submission_state?: 'not_submitted' | 'unknown';
+    signature?: string;
+    details?: unknown;
+}
+declare class TransactionTransportError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly submissionState?: 'not_submitted' | 'unknown';
+    readonly signature?: string;
+    readonly details?: unknown;
+    readonly status: number;
+    constructor(status: number, body: TransactionTransportErrorBody);
+}
+interface TransactionTransport {
+    getLatestBlockhash(options?: TransactionRequestContext): Promise<LatestBlockhashResult>;
+    getFeeForMessage(message: string, options?: TransactionRequestContext): Promise<TransactionFeeResult>;
+    simulateTransaction(transaction: string, options?: TransactionSimulationOptions): Promise<TransactionSimulationResult>;
+    sendTransaction(transaction: string, options?: TransactionSendOptions): Promise<TransactionSendResult>;
+    getSignatureStatus(signature: string, options?: TransactionRequestContext & {
+        searchTransactionHistory?: boolean;
+    }): Promise<TransactionSignatureStatus | null>;
+    getBlockHeight(options?: TransactionRequestContext): Promise<bigint>;
+}
+type AuthenticatedTransactionFetch = (input: string, init: RequestInit, scope: TransactionAuthScope, allowAuthReplay: boolean) => Promise<Response>;
+declare function createTransactionTransport(baseUrl: string, authenticatedFetch: AuthenticatedTransactionFetch): TransactionTransport;
+
 /**
  * Wallet adapter boundary for the Arete SDK.
  *
@@ -7,6 +82,7 @@
  * boundary, implemented by adapters that wrap the Solana library of your choice
  * (@solana/web3.js, @solana/kit, a raw Keypair signer for scripts, etc.).
  */
+
 /**
  * A single account reference within a built instruction.
  */
@@ -70,6 +146,35 @@ interface SendResult {
     /** Slot in which the transaction landed, if the adapter reports it */
     slot?: number;
 }
+/**
+ * Adapter-specific options for unsigned transaction inspection.
+ *
+ * Inspection must not sign or submit the transaction. Concrete adapters may
+ * accept additional simulation options through this passthrough object.
+ */
+interface TransactionInspectionOptions {
+    [key: string]: unknown;
+}
+/**
+ * Unsigned transaction inspection returned by a capable wallet adapter.
+ */
+interface TransactionInspectionResult {
+    /** Estimated transaction fee in lamports, when available. */
+    feeLamports?: number;
+    /** Program logs produced by simulation, when available. */
+    logs?: readonly string[];
+    /** Compute units consumed by simulation, when available. */
+    computeUnitsConsumed?: number;
+    /** RPC context slot for the inspection, when available. */
+    contextSlot?: number;
+    /** Raw simulation failure, if the inspected transaction would fail. */
+    error?: unknown;
+    /** Adapter-specific inspection fields. */
+    [key: string]: unknown;
+}
+interface WalletExecutionContext {
+    transactionTransport?: TransactionTransport;
+}
 /**
  * Wallet adapter interface for signing and sending transactions.
  *
@@ -93,7 +198,14 @@ interface WalletAdapter {
      * @param options - Adapter-specific send/confirmation options
      * @returns The transaction signature (and slot, if known)
      */
-    signAndSend(instructions: readonly BuiltInstruction[], options?: SendOptions): Promise<SendResult>;
+    signAndSend(instructions: readonly BuiltInstruction[], options?: SendOptions, context?: WalletExecutionContext): Promise<SendResult>;
+    /**
+     * Inspect a transaction without signing, submitting, or prompting a wallet.
+     *
+     * This capability is optional because not every adapter has an RPC-backed
+     * unsigned simulation implementation.
+     */
+    inspectTransaction?(instructions: readonly BuiltInstruction[], options?: TransactionInspectionOptions, context?: WalletExecutionContext): Promise<TransactionInspectionResult>;
 }
 /**
  * Wallet connection state
@@ -272,6 +384,7 @@ declare function createPublicKeySeed(address: string): Uint8Array;
  * This module handles serializing instruction arguments into the binary format
  * expected by Solana programs using Borsh serialization.
  */
+
 /**
  * Instruction argument schema for serialization.
  */
@@ -352,6 +465,46 @@ interface ErrorMetadata {
     name: string;
     msg: string;
 }
+type TransactionFailureStatus = 'not-submitted' | 'submitted-unknown' | 'chain-failed';
+type TransactionFailurePhase = 'build' | 'wallet' | 'send' | 'confirmation' | 'chain';
+interface ConfirmedTransactionOutcome {
+    readonly status: 'confirmed';
+    readonly phase: 'confirmation';
+    readonly signature: string;
+    readonly slot?: number;
+}
+interface NotSubmittedTransactionOutcome {
+    readonly status: 'not-submitted';
+    readonly phase: 'build' | 'wallet' | 'send';
+    readonly cause: unknown;
+}
+interface SubmittedUnknownTransactionOutcome {
+    readonly status: 'submitted-unknown';
+    readonly phase: 'send' | 'confirmation';
+    readonly signature: string;
+    readonly slot?: number;
+    readonly cause: unknown;
+}
+interface ChainFailedTransactionOutcome {
+    readonly status: 'chain-failed';
+    readonly phase: 'confirmation' | 'chain';
+    readonly signature?: string;
+    readonly slot?: number;
+    readonly programError?: ProgramError;
+    readonly cause: unknown;
+}
+type TransactionFailureOutcome = NotSubmittedTransactionOutcome | SubmittedUnknownTransactionOutcome | ChainFailedTransactionOutcome;
+type TransactionOutcome = ConfirmedTransactionOutcome | TransactionFailureOutcome;
+/**
+ * Structured transaction failure thrown by adapters and the core executor.
+ */
+declare class TransactionExecutionError extends Error {
+    readonly outcome: TransactionFailureOutcome;
+    readonly cause: unknown;
+    readonly signature?: string;
+    readonly slot?: number;
+    constructor(outcome: TransactionFailureOutcome, message?: string);
+}
 /**
  * Parses an error returned from a Solana transaction.
  *
@@ -359,7 +512,7 @@ interface ErrorMetadata {
  * @param errorMetadata - Error definitions from the IDL
  * @returns Parsed program error or null if not a program error
  */
-declare function parseInstructionError(error: unknown, errorMetadata: ErrorMetadata[]): ProgramError | null;
+declare function parseInstructionError(error: unknown, errorMetadata: readonly ErrorMetadata[]): ProgramError | null;
 /**
  * Formats an error for display.
  *
@@ -376,8 +529,18 @@ declare class InstructionError extends Error {
     readonly programError: ProgramError | null;
     /** The original underlying error from the wallet adapter / RPC. */
     readonly cause: unknown;
-    constructor(message: string, programError: ProgramError | null, cause: unknown);
+    /** Structured chain-failure outcome, including signature and slot when known. */
+    readonly outcome: ChainFailedTransactionOutcome;
+    readonly signature?: string;
+    readonly slot?: number;
+    constructor(message: string, programError: ProgramError | null, cause: unknown, outcome?: ChainFailedTransactionOutcome);
 }
+/** Find a structured transaction failure through nested error causes. */
+declare function getTransactionFailureOutcome(error: unknown): TransactionFailureOutcome | null;
+/**
+ * Normalize an adapter/host exception without retrying or resubmitting.
+ */
+declare function normalizeTransactionError(cause: unknown, errorMetadata?: readonly ErrorMetadata[], fallbackPhase?: 'wallet' | 'send'): InstructionError | TransactionExecutionError;
 
 /**
  * Resolved accounts map passed to a handler's build function.
@@ -546,6 +709,9 @@ type Update<T> = {
     type: 'patch';
     key: string;
     data: Partial<T>;
+} | {
+    type: 'remove';
+    key: string;
 } | {
     type: 'delete';
     key: string;
@@ -560,15 +726,23 @@ type RichUpdate<T> = {
     before: T;
     after: T;
     patch?: unknown;
+} | {
+    type: 'removed';
+    key: string;
+    lastKnown?: T;
 } | {
     type: 'deleted';
     key: string;
     lastKnown?: T;
 };
-interface ViewDef<T, TMode extends 'state' | 'list'> {
+type ViewKeyValue = string | number | bigint;
+type ViewKeyFields<TKey> = unknown extends TKey ? readonly string[] : TKey extends object ? readonly Extract<keyof TKey, string>[] : readonly string[];
+interface ViewDef<T, TMode extends 'state' | 'list', TKey = unknown> {
     readonly mode: TMode;
     readonly view: string;
+    readonly keyFields?: ViewKeyFields<TKey>;
     readonly _entity?: T;
+    readonly _key?: TKey;
 }
 interface StackEndpoints {
     readonly ws: string;
@@ -600,6 +774,8 @@ interface StackQueryDefinition<TParams = unknown, TResult = unknown> {
 interface ProgramSdkDefinition {
     readonly name: string;
     readonly programId?: string;
+    /** Stable fingerprint of the generated program behavior used for client caching. */
+    readonly definitionHash?: string;
     readonly schemas?: Record<string, Schema<unknown>>;
     readonly pdas?: Record<string, unknown>;
     readonly accounts?: Record<string, ProgramAccountReadDefinition<unknown>>;
@@ -620,23 +796,56 @@ interface StackDefinition {
     readonly programs?: Record<string, ProgramSdkDefinition>;
 }
 interface ViewGroup {
-    state?: ViewDef<unknown, 'state'>;
-    list?: ViewDef<unknown, 'list'>;
+    state?: ViewDef<any, 'state', any>;
+    list?: ViewDef<any, 'list'>;
 }
-interface Subscription {
+interface SubscriptionQuery {
     view: string;
     key?: string;
     partition?: string;
-    filters?: Record<string, string>;
+    filters?: Record<string, unknown>;
     take?: number;
     skip?: number;
-    /** Whether to include initial snapshot (defaults to true for backward compatibility) */
-    withSnapshot?: boolean;
-    /** Cursor for resuming from a specific point (_seq value) */
     after?: string;
-    /** Maximum number of entities to include in snapshot (pagination hint) */
     snapshotLimit?: number;
 }
+interface SubscriptionSnapshotOptions {
+    enabled: boolean;
+}
+/** Protocol v2 wire subscription. The client-selected ID remains stable across reconnects. */
+interface Subscription {
+    type: 'subscribe';
+    protocolVersion: 2;
+    subscriptionId: string;
+    query: SubscriptionQuery;
+    snapshot: SubscriptionSnapshotOptions;
+}
+interface SubscriptionRequest {
+    query: SubscriptionQuery;
+    snapshot?: Partial<SubscriptionSnapshotOptions>;
+}
+/** Canonical query identity includes every server query field and snapshot behavior. */
+type SubscriptionIdentity = SubscriptionRequest;
+type SubscriptionOptions = SubscriptionSnapshotOptions;
+interface QuerySnapshot<T = unknown> {
+    readonly subscriptionId: string;
+    readonly query: SubscriptionQuery;
+    readonly keys: readonly string[];
+    readonly data: readonly T[];
+    readonly isLoading: boolean;
+    readonly isRefreshing: boolean;
+    readonly error?: AreteError;
+}
+interface QueryLease {
+    readonly subscription: Subscription;
+    readonly queryKey: string;
+    getSnapshot<T = unknown>(): QuerySnapshot<T>;
+    onChange(callback: () => void): UnsubscribeFn;
+    onUpdate<T = unknown>(callback: (update: Update<T>) => void): UnsubscribeFn;
+    onRichUpdate<T = unknown>(callback: (update: RichUpdate<T>) => void): UnsubscribeFn;
+    refresh(): Promise<void>;
+    release(): void;
+}
 type SchemaResult<T> = {
     success: true;
     data: T;
@@ -648,9 +857,10 @@ interface Schema<T> {
     safeParse: (input: unknown) => SchemaResult<T>;
 }
 interface WatchOptions<TSchema = unknown> {
+    partition?: string;
     take?: number;
     skip?: number;
-    filters?: Record<string, string>;
+    filters?: Record<string, unknown>;
     schema?: Schema<TSchema>;
     /** Whether to include initial snapshot (defaults to true) */
     withSnapshot?: boolean;
@@ -661,6 +871,9 @@ interface WatchOptions<TSchema = unknown> {
 }
 interface AreteOptions<TStack extends StackDefinition> {
     stack: TStack;
+    /** Connect immediately when the client is created (defaults to true). */
+    autoConnect?: boolean;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
     autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
@@ -671,6 +884,10 @@ interface AuthTokenResult {
     token: string;
     expiresAt?: number;
     expires_at?: number;
+    scopes?: readonly string[];
+}
+interface AuthTokenRequest {
+    scopes: readonly string[];
 }
 interface WebSocketFactoryInit {
     headers?: Record<string, string>;
@@ -680,7 +897,7 @@ interface WebSocketFactoryInit {
  */
 interface AuthConfig {
     /** Custom token provider function - called before each connection and during refresh */
-    getToken?: () => Promise<string | AuthTokenResult>;
+    getToken?: (request?: AuthTokenRequest) => Promise<string | AuthTokenResult>;
     /** Arete Cloud token endpoint URL */
     tokenEndpoint?: string;
     /** Publishable key for Arete Cloud */
@@ -699,6 +916,8 @@ interface AuthConfig {
 interface AreteConfig {
     /** WebSocket endpoint. `null`/omitted disables the WebSocket transport (HTTP-only mode). */
     websocketUrl?: string | null;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
+    autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     initialSubscriptions?: Subscription[];
@@ -709,14 +928,15 @@ interface AreteConfig {
 interface SocketIssue {
     error: string;
     message: string;
-    code: AuthErrorCode;
+    code: string | AuthErrorCode;
     retryable: boolean;
     retryAfter?: number;
     suggestedAction?: string;
     docsUrl?: string;
     fatal: boolean;
+    subscriptionId?: string | null;
 }
-declare const DEFAULT_CONFIG: Required<Pick<AreteConfig, 'reconnectIntervals' | 'maxReconnectAttempts' | 'maxEntriesPerView'>>;
+declare const DEFAULT_CONFIG: Required<Pick<AreteConfig, 'autoReconnect' | 'reconnectIntervals' | 'maxReconnectAttempts' | 'maxEntriesPerView'>>;
 /**
  * Machine-readable error codes for authentication and rate limiting failures
  *
@@ -732,21 +952,22 @@ type TypedViews<TViews extends StackDefinition['views']> = {
     [K in keyof TViews]: TypedViewGroup<TViews[K]>;
 };
 type TypedViewGroup<TGroup> = {
-    [K in keyof TGroup]: TGroup[K] extends ViewDef<infer T, 'state'> ? TypedStateView<T> : TGroup[K] extends ViewDef<infer T, 'list'> ? TypedListView<T> : never;
+    [K in keyof TGroup]: TGroup[K] extends ViewDef<infer T, 'state', infer TKey> ? TypedStateView<T, DefaultViewKey<TKey>> : TGroup[K] extends ViewDef<infer T, 'list'> ? TypedListView<T> : never;
 };
-interface TypedStateView<T> {
-    use<TSchema = T>(key: string, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
-    watch(key: string, options?: WatchOptions): AsyncIterable<Update<T>>;
-    watchRich(key: string, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
-    get(key: string): Promise<T | null>;
-    getSync(key: string): T | null | undefined;
+type DefaultViewKey<TKey> = unknown extends TKey ? string : TKey;
+interface TypedStateView<T, TKey = string> {
+    use<TSchema = T>(key: TKey, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
+    watch(key: TKey, options?: WatchOptions): AsyncIterable<Update<T>>;
+    watchRich(key: TKey, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
+    get(key: TKey, options?: WatchOptions): Promise<T | null>;
+    getSync(key: TKey, options?: WatchOptions): T | null | undefined;
 }
 interface TypedListView<T> {
     use<TSchema = T>(options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
     watch(options?: WatchOptions): AsyncIterable<Update<T>>;
     watchRich(options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
-    get(): Promise<T[]>;
-    getSync(): T[] | undefined;
+    get(options?: WatchOptions): Promise<T[]>;
+    getSync(options?: WatchOptions): T[] | undefined;
 }
 type SubscribeCallback<T> = (update: Update<T>) => void;
 type UnsubscribeFn = () => void;
@@ -754,52 +975,77 @@ type ConnectionStateCallback = (state: ConnectionState, error?: string) => void;
 type SocketIssueCallback = (issue: SocketIssue) => void;
 
 type FrameMode = 'state' | 'append' | 'list';
-type FrameOp = 'create' | 'upsert' | 'patch' | 'delete' | 'snapshot' | 'subscribed';
+type FrameOp = 'subscribed' | 'unsubscribed' | 'snapshot' | 'upsert' | 'patch' | 'remove' | 'delete';
 type SortOrder = 'asc' | 'desc';
 interface SortConfig {
     field: string[];
     order: SortOrder;
 }
-interface SubscribedFrame {
+interface IdentifiedFrame {
+    protocolVersion: 2;
+    subscriptionId: string;
+}
+interface SubscribedFrame extends IdentifiedFrame {
     op: 'subscribed';
-    view: string;
+    query: SubscriptionQuery;
     mode: FrameMode;
     sort?: SortConfig;
 }
-interface EntityFrame<T = unknown> {
+interface UnsubscribedFrame extends IdentifiedFrame {
+    op: 'unsubscribed';
+}
+interface EntityFrame<T = unknown> extends IdentifiedFrame {
     mode: FrameMode;
     entity: string;
-    op: FrameOp;
+    op: 'upsert' | 'patch' | 'remove' | 'delete';
     key: string;
-    data: T;
+    data: T | null;
     append?: string[];
-    /** Sequence cursor for ordering and resume capability */
     seq?: string;
 }
 interface SnapshotEntity<T = unknown> {
     key: string;
     data: T;
 }
-interface SnapshotFrame<T = unknown> {
+interface SnapshotFrame<T = unknown> extends IdentifiedFrame {
+    snapshotId: string;
+    authoritative: boolean;
     mode: FrameMode;
     entity: string;
     op: 'snapshot';
+    key?: string;
     data: SnapshotEntity<T>[];
-    /** Indicates if this is the final snapshot batch. When false, more batches will follow. */
-    complete?: boolean;
+    complete: boolean;
+}
+interface ErrorFrame {
+    type: 'error';
+    protocolVersion: 2;
+    subscriptionId: string | null;
+    error?: string;
+    message?: string;
+    code: string;
+    retryable?: boolean;
+    fatal: boolean;
+    retry_after?: number;
+    suggested_action?: string;
+    docs_url?: string;
 }
-type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame;
+type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame | UnsubscribedFrame | ErrorFrame;
 declare function isSnapshotFrame<T>(frame: Frame<T>): frame is SnapshotFrame<T>;
 declare function isSubscribedFrame(frame: Frame): frame is SubscribedFrame;
+declare function isUnsubscribedFrame(frame: Frame): frame is UnsubscribedFrame;
+declare function isErrorFrame(frame: Frame): frame is ErrorFrame;
 declare function isEntityFrame<T>(frame: Frame<T>): frame is EntityFrame<T>;
 declare function parseFrame(data: ArrayBuffer | string): Frame;
 declare function parseFrameFromBlob(blob: Blob): Promise<Frame>;
 declare function isValidFrame(frame: unknown): frame is Frame;
 
 type FrameHandler = <T>(frame: Frame<T>) => void;
+declare function isHostedAreteEndpoint(url: string): boolean;
 declare class ConnectionManager {
     private ws;
     private websocketUrl;
+    private readonly autoReconnect;
     private reconnectIntervals;
     private maxReconnectAttempts;
     private reconnectAttempts;
@@ -807,15 +1053,20 @@ declare class ConnectionManager {
     private pingInterval;
     private tokenRefreshTimeout;
     private tokenRefreshInFlight;
+    private tokenRequestInFlight;
     private currentState;
     private subscriptionQueue;
     private activeSubscriptions;
+    private socketGeneration;
+    private pendingConnect;
     private frameHandlers;
     private stateHandlers;
     private socketIssueHandlers;
     private authConfig?;
     private currentToken?;
     private tokenExpiry?;
+    private tokenScopes;
+    private requestedScopes;
     private readonly hostedAreteUrl;
     private reconnectForTokenRefresh;
     constructor(config: AreteConfig);
@@ -824,7 +1075,9 @@ declare class ConnectionManager {
     private hasRefreshableAuth;
     private updateTokenState;
     private clearTokenState;
+    private tokenCovers;
     private getOrRefreshToken;
+    private fetchAuthToken;
     private createTokenEndpointRequestBody;
     private fetchTokenFromEndpoint;
     private isTokenExpired;
@@ -840,19 +1093,21 @@ declare class ConnectionManager {
     private createWebSocket;
     getState(): ConnectionState;
     getHttpAuthToken(forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(requiredScopes?: readonly string[], forceRefresh?: boolean): Promise<string | undefined>;
     clearHttpAuthToken(): void;
     onFrame(handler: FrameHandler): () => void;
     onStateChange(handler: ConnectionStateCallback): () => void;
     onSocketIssue(handler: SocketIssueCallback): () => void;
     private notifySocketIssue;
-    connect(): Promise<void>;
+    connect(recovering?: boolean): Promise<void>;
     disconnect(): void;
     subscribe(subscription: Subscription): void;
-    unsubscribe(view: string, key?: string): void;
+    unsubscribe(subscriptionId: string): void;
+    refresh(subscription: Subscription): void;
     isConnected(): boolean;
-    private makeSubKey;
     private flushSubscriptionQueue;
     private resubscribeActive;
+    private addQueuedSubscription;
     private updateState;
     private notifyFrameHandlers;
     private handleReconnect;
@@ -893,16 +1148,169 @@ interface StorageAdapter {
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
 }
 
+declare class QueryStore {
+    private readonly storage;
+    private readonly records;
+    constructor(storage: StorageAdapter);
+    register(subscription: Subscription, queryKey: string): void;
+    unregister(subscriptionId: string): void;
+    getSubscription(subscriptionId: string): Subscription | undefined;
+    getQueryKey(subscriptionId: string): string | undefined;
+    getSnapshot<T>(subscriptionId: string): QuerySnapshot<T> | undefined;
+    onChange(subscriptionId: string, callback: () => void): UnsubscribeFn;
+    onUpdate<T>(subscriptionId: string, callback: (update: Update<T>) => void): UnsubscribeFn;
+    onRichUpdate<T>(subscriptionId: string, callback: (update: RichUpdate<T>) => void): UnsubscribeFn;
+    acknowledge(subscriptionId: string, effectiveQuery: SubscriptionQuery, mode: FrameMode, sort?: SortConfig): void;
+    stageSnapshot(frame: SnapshotFrame, keys: readonly string[]): void;
+    applyLive(subscriptionId: string, key: string, update: Update<unknown>, richUpdate?: RichUpdate<unknown>, sequence?: string): void;
+    deleteGlobal(view: string, key: string, lastKnown?: unknown): void;
+    evict(view: string, key: string): void;
+    failFrame(frame: ErrorFrame): void;
+    beginRefresh(subscriptionId: string, waitForSnapshot?: boolean): Promise<void>;
+    failRefresh(subscriptionId: string, error: AreteError): void;
+    beginReconnect(): void;
+    failRefreshing(error: AreteError): void;
+    clear(): void;
+    private mergeIncremental;
+    private sortKeys;
+    private entitySequence;
+    private fail;
+    private resolveRefresh;
+    private rejectRefresh;
+    private requireRecord;
+    private touch;
+    private emitUpdate;
+    private emitRichUpdate;
+}
+
+interface WaitForProcessedSlotOptions {
+    /** Reject if the requested slot has not been processed within this duration. */
+    timeoutMs?: number;
+    /** Abort this wait without affecting frame processing or the connection. */
+    signal?: AbortSignal;
+}
+declare class ProcessedSlotTimeoutError extends Error {
+    readonly targetSlot: bigint;
+    readonly processedSlot: bigint | null;
+    constructor(targetSlot: bigint, processedSlot: bigint | null);
+}
+interface FrameProcessorConfig {
+    maxEntriesPerView?: number | null;
+    /**
+     * Interval in milliseconds to buffer frames before flushing to storage.
+     * Set to 0 for immediate processing (no buffering).
+     * Default: 0 (immediate)
+     *
+     * For React applications, 16ms (one frame at 60fps) is recommended to
+     * reduce unnecessary re-renders during high-frequency updates.
+     */
+    flushIntervalMs?: number;
+    schemas?: Record<string, Schema<unknown>>;
+    patchSchemas?: Record<string, Schema<unknown>>;
+    queryStore?: QueryStore;
+    /** Whether rejected frames should also be written to `console.warn`. */
+    warnOnValidationError?: boolean;
+    /** Receives structured details whenever a generated schema rejects a frame. */
+    onValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
+}
+interface FrameValidationDiagnostic {
+    readonly view: string;
+    readonly key?: string;
+    readonly seq?: string;
+    readonly operation: 'snapshot' | 'upsert' | 'patch';
+    readonly error: unknown;
+}
+declare class FrameProcessor {
+    private storage;
+    private maxEntriesPerView;
+    private flushIntervalMs;
+    private schemas?;
+    private patchSchemas?;
+    private queryStore?;
+    private warnOnValidationError;
+    private onValidationError?;
+    private pendingUpdates;
+    private flushTimer;
+    private isProcessing;
+    private latestProcessedSlot;
+    private processedSlotWaiters;
+    constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
+    private getSchema;
+    private normalizeEntity;
+    private hasSchema;
+    private normalizePathSegment;
+    private normalizePath;
+    private normalizeSortConfig;
+    private normalizeAppendPaths;
+    private extractSeq;
+    private getInternalSeq;
+    private compareSeq;
+    private attachInternalSeq;
+    handleFrame<T>(frame: Frame<T>): void;
+    /**
+     * Immediately flush all pending updates.
+     * Useful for ensuring all updates are processed before reading state.
+     */
+    flush(): void;
+    getProcessedSlot(): bigint | null;
+    waitForProcessedSlot(slot: number | bigint, options?: WaitForProcessedSlotOptions): Promise<bigint>;
+    /**
+     * Clean up any pending timers. Call when disposing the processor.
+     */
+    dispose(): void;
+    private scheduleFlush;
+    private flushPendingUpdates;
+    private processFrame;
+    private normalizeSlot;
+    private slotFromSeq;
+    private frameSlot;
+    private markFrameProcessed;
+    private removeProcessedSlotWaiter;
+    private createAbortError;
+    private processFrameWithoutEnforce;
+    private handleSubscribedFrame;
+    private handleSnapshotFrame;
+    private handleSnapshotFrameWithoutEnforce;
+    private handleEntityFrame;
+    private handleEntityFrameWithoutEnforce;
+    private emitRichUpdate;
+    private createRichUpdate;
+    private enforceMaxEntries;
+}
+
+interface NormalizedSubscriptionRequest {
+    query: SubscriptionQuery;
+    snapshot: SubscriptionSnapshotOptions;
+}
+declare function validateSubscriptionId(subscriptionId: string): void;
+declare function createSubscriptionId(): string;
+declare function normalizeSubscriptionQuery(query: SubscriptionQuery): SubscriptionQuery;
+declare function normalizeSubscriptionRequest(request: SubscriptionRequest): NormalizedSubscriptionRequest;
+declare function canonicalQueryKey(request: SubscriptionRequest): string;
+declare function normalizeSubscription(subscription: Subscription): Subscription;
 declare class SubscriptionRegistry {
-    private subscriptions;
-    private connection;
-    constructor(connection: ConnectionManager);
-    subscribe(subscription: Subscription): UnsubscribeFn;
-    unsubscribe(subscription: Subscription): void;
-    getRefCount(subscription: Subscription): number;
+    private readonly connection;
+    private readonly queryStore;
+    private readonly subscriptions;
+    private readonly subscriptionsById;
+    constructor(connection: ConnectionManager, queryStore: QueryStore);
+    subscribe(query: SubscriptionQuery, snapshotEnabled?: boolean): QueryLease;
+    refresh(query: SubscriptionQuery, snapshotEnabled?: boolean): Promise<void>;
+    /**
+     * 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: string, key?: string): Promise<void>;
+    getRefCount(query: SubscriptionQuery, snapshotEnabled?: boolean): number;
     getActiveSubscriptions(): Subscription[];
+    getSnapshot<T>(query: SubscriptionQuery, snapshotEnabled?: boolean): QuerySnapshot<T> | undefined;
+    handleConnectionState(state: ConnectionState): void;
     clear(): void;
-    private makeSubKey;
+    private createLease;
+    private getTracker;
+    private refreshTracker;
+    private releaseTracker;
 }
 
 interface ChainClock {
@@ -936,6 +1344,19 @@ interface TokenBalanceInfo {
     amount: string;
     decimals?: number | null;
     uiAmountString?: string | null;
+    contextSlot: bigint;
+}
+interface NativeBalanceInfo {
+    lamports: bigint;
+    contextSlot: bigint;
+}
+interface ContextSlotOptions {
+    minContextSlot?: number | bigint;
+}
+interface TokenBalanceInput {
+    owner: string;
+    mint: string;
+    tokenProgram?: string;
 }
 interface RawAccountInfo {
     address: string;
@@ -947,16 +1368,13 @@ interface RawAccountInfo {
 interface ChainClient {
     exists(address: string): Promise<boolean>;
     lamports(address: string): Promise<number>;
+    nativeBalance(address: string, options?: ContextSlotOptions): Promise<NativeBalanceInfo>;
     minimumBalanceForRentExemption(space: number): Promise<number>;
     clock(): Promise<ChainClock>;
     account(address: string): Promise<RawAccountInfo | null>;
     mint(address: string): Promise<MintAccountInfo | null>;
     tokenAccount(address: string): Promise<TokenAccountInfo | null>;
-    balance(input: {
-        owner: string;
-        mint: string;
-        tokenProgram?: string;
-    }): Promise<TokenBalanceInfo>;
+    balance(input: TokenBalanceInput, options?: ContextSlotOptions): Promise<TokenBalanceInfo>;
 }
 type FetchLike = typeof fetch;
 declare function deriveHttpEndpoint(wsUrl: string): string;
@@ -1000,6 +1418,19 @@ interface PreparedOperationDescription {
         }[];
     }[];
 }
+interface OperationInspection {
+    /** JSON-safe description produced by {@link describePreparedOperation}. */
+    readonly description: PreparedOperationDescription;
+    /** Raw unsigned inspection returned by the adapter. */
+    readonly transaction: TransactionInspectionResult;
+    /** IDL-aware program error parsed from the inspection failure, if any. */
+    readonly programError: ProgramError | null;
+}
+interface OperationInspectionOptions {
+    wallet?: WalletAdapter;
+    inspect?: TransactionInspectionOptions;
+    transactionTransport?: TransactionTransport;
+}
 interface PreparedTransactionBody {
     readonly name: string;
     readonly instructions: NonEmptyReadonlyArray<BuiltInstruction>;
@@ -1079,6 +1510,7 @@ interface SingleTransactionOperationReceipt<TArtifacts> {
     readonly artifacts: TArtifacts;
     readonly signatures: NonEmptyReadonlyArray<string>;
     readonly transaction: OperationTransactionReceipt;
+    readonly callbackErrors?: readonly OperationCallbackError[];
 }
 interface FlowOperationReceipt<TArtifacts> {
     readonly kind: 'flow';
@@ -1086,6 +1518,7 @@ interface FlowOperationReceipt<TArtifacts> {
     readonly artifacts: TArtifacts;
     readonly signatures: NonEmptyReadonlyArray<string>;
     readonly transactions: NonEmptyReadonlyArray<OperationTransactionReceipt>;
+    readonly callbackErrors?: readonly OperationCallbackError[];
 }
 type OperationReceiptFor<TPrepared extends PreparedOperation> = TPrepared extends PreparedFlow<infer TArtifacts> ? FlowOperationReceipt<TArtifacts> : TPrepared extends PreparedInstruction<infer TArtifacts> ? SingleTransactionOperationReceipt<TArtifacts> : TPrepared extends PreparedTransaction<infer TArtifacts> ? SingleTransactionOperationReceipt<TArtifacts> : never;
 interface OperationExecutionEvent<TPrepared extends PreparedOperation = PreparedOperation> {
@@ -1096,14 +1529,18 @@ interface OperationExecutionEvent<TPrepared extends PreparedOperation = Prepared
 interface OperationExecutionSuccessEvent<TPrepared extends PreparedOperation = PreparedOperation> extends OperationExecutionEvent<TPrepared> {
     readonly receipt: OperationTransactionReceipt;
 }
+type OperationCallbackPhase = 'transaction-start' | 'transaction-success';
 interface OperationExecutionOptions<TSigner = unknown, TPrepared extends PreparedOperation = PreparedOperation> {
     wallet?: WalletAdapter;
+    transactionTransport?: TransactionTransport;
     send?: SendOptions;
     signers?: readonly TSigner[];
     signerRegistry?: SignerRegistry<TSigner>;
     availableSignerAddresses?: readonly string[];
     onTransactionStart?: (event: OperationExecutionEvent<TPrepared>) => void | Promise<void>;
     onTransactionSuccess?: (event: OperationExecutionSuccessEvent<TPrepared>) => void | Promise<void>;
+    /** Receives observer failures without changing the transaction outcome. */
+    onCallbackError?: (error: OperationCallbackError<TPrepared>) => void | Promise<void>;
 }
 interface OperationExecutionHost<TSigner = unknown> {
     readonly wallet?: WalletAdapter;
@@ -1113,28 +1550,60 @@ interface OperationExecutionHost<TSigner = unknown> {
         send?: SendOptions;
         errors?: ErrorMetadata[];
         signers?: readonly TSigner[];
+        transactionTransport?: TransactionTransport;
     }): Promise<{
         signature: string;
         slot?: number;
     }>;
 }
+declare class OperationCallbackError<TPrepared extends PreparedOperation = PreparedOperation> extends Error {
+    readonly phase: OperationCallbackPhase;
+    readonly operation: TPrepared;
+    readonly transaction: PreparedTransactionBody;
+    readonly transactionIndex: number;
+    readonly receipt?: OperationTransactionReceipt;
+    readonly cause: unknown;
+    constructor(input: {
+        phase: OperationCallbackPhase;
+        operation: TPrepared;
+        transaction: PreparedTransactionBody;
+        transactionIndex: number;
+        receipt?: OperationTransactionReceipt;
+        cause: unknown;
+    });
+}
 declare class OperationExecutionError<TPrepared extends PreparedOperation = PreparedOperation> extends Error {
     readonly operation: TPrepared;
     readonly failedTransaction: PreparedTransactionBody;
     readonly failedTransactionIndex: number;
     readonly completedReceipts: readonly OperationTransactionReceipt[];
+    readonly callbackErrors: readonly OperationCallbackError<TPrepared>[];
+    readonly outcome: TransactionFailureOutcome;
+    readonly signature?: string;
+    readonly slot?: number;
     readonly cause: unknown;
     constructor(input: {
         operation: TPrepared;
         failedTransaction: PreparedTransactionBody;
         failedTransactionIndex: number;
         completedReceipts: readonly OperationTransactionReceipt[];
+        callbackErrors?: readonly OperationCallbackError<TPrepared>[];
+        outcome?: TransactionFailureOutcome;
         cause: unknown;
     });
 }
 declare function executePreparedOperation<TPrepared extends PreparedOperation, TSigner = unknown>(host: OperationExecutionHost<TSigner>, operation: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
+/**
+ * Recursively unwrap operation context while retaining structured transaction outcomes.
+ */
+declare function unwrapOperationExecutionError(error: unknown): InstructionError | TransactionFailureOutcome | unknown;
 declare function toJsonValue(value: unknown): JsonValue;
 declare function describePreparedOperation(operation: PreparedOperation): PreparedOperationDescription;
+/**
+ * Inspect one prepared instruction/transaction without signing or submission.
+ * Multi-transaction flows are intentionally unsupported.
+ */
+declare function inspectPreparedOperation(wallet: WalletAdapter | undefined, operation: PreparedOperation, options?: TransactionInspectionOptions, context?: WalletExecutionContext): Promise<OperationInspection>;
 declare function formatPreparedOperation(operation: PreparedOperation): string;
 
 interface InstructionOperation<TInput = unknown, TArtifacts = void> {
@@ -1164,6 +1633,16 @@ declare function flowOperation<TInput, TArtifacts>(prepare: (input: TInput) => M
 declare const STACK_RUNTIME_EXTENSIONS: "__areteStackRuntimeExtensions";
 declare const PROGRAM_OPERATION_EXTENSIONS: "__areteProgramOperationExtensions";
 type EmptyRecord = Record<string, never>;
+/** Fixed arity, or `[required, total]` when a read has optional arguments. */
+type ReadArgumentCount = number | readonly [required: number, total: number];
+type RequiredArgumentCount<TArgs extends readonly unknown[], TCount extends readonly unknown[] = []> = TArgs extends readonly [infer THead, ...infer TTail] ? undefined extends THead ? TCount['length'] : RequiredArgumentCount<TTail, readonly [...TCount, unknown]> : TCount['length'];
+type ReadArgumentCountFor<TRead> = TRead extends (...args: infer TArgs) => unknown ? number extends Required<TArgs>['length'] ? ReadArgumentCount : RequiredArgumentCount<TArgs> extends Required<TArgs>['length'] ? Required<TArgs>['length'] : readonly [
+    required: RequiredArgumentCount<TArgs>,
+    total: Required<TArgs>['length']
+] : never;
+type ReadArgumentCounts<TRead = Record<string, unknown>> = {
+    readonly [K in keyof TRead]: ReadArgumentCountFor<TRead[K]>;
+};
 type MaybeField<TKey extends string, TValue> = [TValue] extends [never] ? {} : {
     readonly [K in TKey]: TValue;
 };
@@ -1195,7 +1674,7 @@ interface ProgramRuntimeExtensionCarrier<TOperations extends AnyProgramOperation
 }
 type ProgramOperationsOf<TProgram> = TProgram extends ProgramRuntimeExtensionCarrier<infer TOperations> ? TOperations : ProgramOperations;
 type MergeProgramOperations<TBase extends AnyProgramOperations, TExtension extends AnyProgramOperations> = ProgramOperations<Extract<MergeField<InstructionOperationsOf<TBase>, InstructionOperationsOf<TExtension>>, InstructionOperationNamespace | EmptyRecord>, Extract<MergeField<TransactionOperationsOf<TBase>, TransactionOperationsOf<TExtension>>, TransactionOperationNamespace | EmptyRecord>, Extract<MergeField<FlowOperationsOf<TBase>, FlowOperationsOf<TExtension>>, FlowOperationNamespace | EmptyRecord>>;
-type ExtendedProgramDefinition<TBase extends ProgramSdkDefinition, TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never> = TBase & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath> & ProgramRuntimeExtensionCarrier<MergeProgramOperations<ProgramOperationsOf<TBase>, TOperations>>;
+type ExtendedProgramDefinition<TBase extends ProgramSdkDefinition, TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never> = Omit<TBase, 'definitionHash'> & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath> & ProgramRuntimeExtensionCarrier<MergeProgramOperations<ProgramOperationsOf<TBase>, TOperations>>;
 interface ProgramExtensionInput<TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TProgram extends ProgramSdkDefinition = ProgramSdkDefinition, TMath = never> {
     readonly pdas?: Record<string, unknown>;
     readonly accounts?: Record<string, unknown>;
@@ -1222,6 +1701,7 @@ declare function extendPrograms<TPrograms extends Record<string, ProgramSdkDefin
 };
 declare function getProgramRuntimeExtensions<TProgram extends ProgramSdkDefinition>(program: TProgram): ProgramRuntimeExtensions<ProgramOperationsOf<TProgram>, TProgram> | undefined;
 interface StackRuntimeExtensions<TRead = EmptyRecord, TFlows extends FlowOperationNamespace | EmptyRecord = EmptyRecord, TClient = unknown> {
+    readonly readArgCounts?: ReadArgumentCounts<TRead>;
     readonly createRead?: (client: TClient) => TRead;
     readonly createFlows?: (client: TClient) => TFlows;
 }
@@ -1238,16 +1718,22 @@ interface StackExtensionInput<TAddresses = never, TConstants = never, TDefaults
     readonly constants?: TConstants;
     readonly defaults?: TDefaults;
     readonly math?: TMath;
+    readonly readArgCounts?: ReadArgumentCounts<TRead>;
     readonly createRead?: (client: TClient) => TRead;
     readonly createFlows?: (client: TClient) => TFlows;
 }
+type ReadArgumentCountRequirement<TExtension> = TExtension extends {
+    readonly createRead: (...args: any[]) => infer TRead;
+} ? {
+    readonly readArgCounts: ReadArgumentCounts<TRead>;
+} : {};
 type StackExtensionClient<TBase extends StackDefinition, TAddresses = never, TConstants = never, TDefaults = never, TMath = never> = Arete$1<TBase> & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath>;
-declare function defineStackExtensions<TBase extends StackDefinition>(): <TExtension extends StackExtensionInput<any, any, any, any, any, FlowOperationNamespace | EmptyRecord, any>>(extensions: TExtension & {
+declare function defineStackExtensions<TBase extends StackDefinition>(): <const TExtension extends StackExtensionInput<any, any, any, any, any, FlowOperationNamespace | EmptyRecord, any>>(extensions: TExtension & ReadArgumentCountRequirement<TExtension> & {
     readonly createRead?: (client: StackExtensionClient<TBase, any, any, any, any>) => unknown;
     readonly createFlows?: (client: StackExtensionClient<TBase, any, any, any, any>) => FlowOperationNamespace | EmptyRecord;
 }) => TExtension;
-declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
-declare function getStackRuntimeExtensions<TStack extends StackDefinition>(stack: TStack): StackRuntimeExtensions | undefined;
+declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension & ReadArgumentCountRequirement<TExtension>): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
+declare function getStackRuntimeExtensions<TStack extends StackDefinition>(stack: TStack): StackRuntimeExtensions<StackReadOf<TStack>> | undefined;
 declare function applyConnectedStackExtensions<TClient extends object, TStack extends StackDefinition>(client: TClient, stack: TStack): ConnectedStackClient<TClient, TStack>;
 
 type ProgramMap = Record<string, ProgramSdkDefinition>;
@@ -1268,11 +1754,21 @@ interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined> {
     transport?: 'ws' | 'http';
     storage?: StorageAdapter;
     maxEntriesPerView?: number | null;
+    /** Connect immediately when the client is created (defaults to true). */
+    autoConnect?: boolean;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
     autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     flushIntervalMs?: number;
+    /**
+     * Generated schemas are always applied to normalize typed entities. Set this
+     * to `false` to suppress console warnings for rejected frames while keeping
+     * schema normalization and `onFrameValidationError` active.
+     */
     validateFrames?: boolean;
+    /** Observe generated-schema rejections without scraping console warnings. */
+    onFrameValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
     /** Authentication configuration */
     auth?: AuthConfig;
     /** Default wallet adapter used for instruction execution (overridable per call). */
@@ -1294,9 +1790,11 @@ interface AreteOptionsWithStorage<TStack extends StackDefinition> extends AreteO
     wallet?: WalletAdapter;
     fetch?: typeof fetch;
     execution?: OperationExecutionOptions<any>;
+    onFrameValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
 }
 interface TransactionOptions<TSigner = unknown> {
     wallet?: WalletAdapter;
+    transactionTransport?: TransactionTransport;
     send?: SendOptions;
     errors?: ErrorMetadata[];
     signers?: readonly TSigner[];
@@ -1365,10 +1863,12 @@ declare class Arete$1<TStack extends StackDefinition> {
     private readonly storage;
     private readonly processor;
     private readonly subscriptionRegistry;
+    private readonly queryStore;
     private readonly _views;
     private readonly _queries;
     private readonly _programs;
     private readonly _chain;
+    private readonly _transactions;
     private readonly stack;
     private readonly httpBaseUrl;
     private readonly fetchImpl;
@@ -1392,6 +1892,7 @@ declare class Arete$1<TStack extends StackDefinition> {
     get queries(): QueriesInterface<TStack['queries']>;
     get programs(): ProgramsInterface<TStack['programs']>;
     get chain(): ChainClient;
+    get transactions(): TransactionTransport;
     /** The default wallet adapter, if one was configured. */
     get wallet(): WalletAdapter | undefined;
     /** The connected wallet address, if a default wallet was configured. */
@@ -1415,11 +1916,20 @@ declare class Arete$1<TStack extends StackDefinition> {
      */
     transaction(instructions: readonly BuiltInstruction[], options?: TransactionOptions): Promise<ExecutionResult>;
     execute<TPrepared extends PreparedOperation, TSigner = unknown>(prepared: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
+    /** Inspect one prepared instruction/transaction without signing or submitting it. */
+    inspectOperation(prepared: PreparedOperation, options?: OperationInspectionOptions): Promise<OperationInspection>;
     /** Error metadata from every handler in the stack, deduped by code. */
     private aggregateErrors;
     get connectionState(): ConnectionState;
     get stackName(): string;
     get store(): StorageAdapter;
+    /** Highest Solana slot whose streamed frame has been stored locally. */
+    get processedSlot(): bigint | null;
+    /**
+     * 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: number | bigint, options?: WaitForProcessedSlotOptions): Promise<bigint>;
     onConnectionStateChange(callback: ConnectionStateCallback): UnsubscribeFn;
     onFrame(callback: (frame: Frame) => void): UnsubscribeFn;
     onSocketIssue(callback: SocketIssueCallback): UnsubscribeFn;
@@ -1430,6 +1940,7 @@ declare class Arete$1<TStack extends StackDefinition> {
     getStore(): StorageAdapter;
     getConnection(): ConnectionManager;
     getSubscriptionRegistry(): SubscriptionRegistry;
+    getQueryStore(): QueryStore;
 }
 
 /**
@@ -1458,6 +1969,7 @@ interface SessionMemberOptions<TPrograms extends Record<string, ProgramSdkDefini
     transport?: 'ws' | 'http';
     auth?: AuthConfig;
     storage?: StorageAdapter;
+    autoConnect?: boolean;
     autoReconnect?: boolean;
     programs?: TPrograms;
 }
@@ -1466,6 +1978,8 @@ interface SessionOptions<TDef extends SessionDefinition = SessionDefinition, TSt
     wallet?: WalletAdapter;
     /** Canonical chain reader shared by the session when explicitly provided. */
     chain?: ChainClient;
+    /** Transaction transport override; defaults to the execution host's authenticated client. */
+    transactions?: TransactionTransport;
     auth?: AuthConfig;
     fetch?: typeof fetch;
     /** Default transport for all members ('ws' unless overridden). */
@@ -1504,6 +2018,7 @@ interface Session<TDef extends SessionDefinition = SessionDefinition, TStackProg
     readonly wallet: WalletAdapter | undefined;
     readonly signerRegistry: SignerRegistry<any>;
     readonly chain: ChainClient;
+    readonly transactions: TransactionTransport;
     transaction(instructions: readonly BuiltInstruction[], options?: TransactionOptions): Promise<ExecutionResult>;
     execute<TPrepared extends PreparedOperation, TSigner = unknown>(prepared: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
     setWallet(wallet: WalletAdapter | undefined): void;
@@ -1549,6 +2064,8 @@ declare function parseUiAmountToRaw(value: string | number, decimals: number): b
 declare function formatRawToUi(raw: bigint | string | number, decimals: number): string;
 /** Resolve an {@link AmountInput} to raw base units with known decimals. */
 declare function toRawAmount(amount: AmountInput, decimals: number): bigint;
+/** Convert an amount to raw units without throwing on invalid user input. */
+declare function safeToRawAmount(amount: AmountInput, decimals: number): SchemaResult<bigint>;
 /** Fetch a mint's decimals via the chain read endpoint, throwing when unavailable. */
 declare function getMintDecimals(chain: ChainClient, mint: string): Promise<number>;
 /**
@@ -1570,6 +2087,24 @@ declare function resolveAmountsToRaw<TInputs extends Record<string, AmountResolu
     [K in keyof TInputs]: bigint;
 }>;
 
+/**
+ * Recursively convert bigints to their decimal string form.
+ *
+ * Streamed entities contain bigints, which makes them unsafe to pass through
+ * anything that JSON-stringifies (React's dev-mode performance tooling, log
+ * pipelines, `JSON.stringify` persistence). Prefer stack-provided UI fields
+ * (e.g. `deployedPerSquareUi`) when they exist; use this for the remaining
+ * raw values such as account snapshots.
+ *
+ * Arrays and plain objects are converted structurally and the return type
+ * maps every `bigint` to `string`; class instances (PublicKey, Date, …) are
+ * returned untouched.
+ */
+type StringifiedBigints<T> = T extends bigint ? string : T extends readonly (infer U)[] ? readonly StringifiedBigints<U>[] : T extends object ? {
+    [K in keyof T]: StringifiedBigints<T[K]>;
+} : T;
+declare function stringifyBigints<T>(value: T): StringifiedBigints<T>;
+
 declare class ReadRequestError extends Error {
     readonly status: number;
     readonly path: string;
@@ -1600,63 +2135,6 @@ declare function stackQuery<TParams = unknown, TResult = unknown>(input: {
     schema?: Schema<TResult>;
 }): StackQueryDefinition<TParams, TResult>;
 
-interface FrameProcessorConfig {
-    maxEntriesPerView?: number | null;
-    /**
-     * Interval in milliseconds to buffer frames before flushing to storage.
-     * Set to 0 for immediate processing (no buffering).
-     * Default: 0 (immediate)
-     *
-     * For React applications, 16ms (one frame at 60fps) is recommended to
-     * reduce unnecessary re-renders during high-frequency updates.
-     */
-    flushIntervalMs?: number;
-    schemas?: Record<string, Schema<unknown>>;
-    patchSchemas?: Record<string, Schema<unknown>>;
-}
-declare class FrameProcessor {
-    private storage;
-    private maxEntriesPerView;
-    private flushIntervalMs;
-    private schemas?;
-    private patchSchemas?;
-    private pendingUpdates;
-    private flushTimer;
-    private isProcessing;
-    constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
-    private getSchema;
-    private normalizeEntity;
-    private hasSchema;
-    private normalizePathSegment;
-    private normalizePath;
-    private normalizeSortConfig;
-    private normalizeAppendPaths;
-    private extractSeq;
-    private getInternalSeq;
-    private attachInternalSeq;
-    handleFrame<T>(frame: Frame<T>): void;
-    /**
-     * Immediately flush all pending updates.
-     * Useful for ensuring all updates are processed before reading state.
-     */
-    flush(): void;
-    /**
-     * Clean up any pending timers. Call when disposing the processor.
-     */
-    dispose(): void;
-    private scheduleFlush;
-    private flushPendingUpdates;
-    private processFrame;
-    private processFrameWithoutEnforce;
-    private handleSubscribedFrame;
-    private handleSnapshotFrame;
-    private handleSnapshotFrameWithoutEnforce;
-    private handleEntityFrame;
-    private handleEntityFrameWithoutEnforce;
-    private emitRichUpdate;
-    private enforceMaxEntries;
-}
-
 declare class MemoryAdapter implements StorageAdapter {
     private views;
     private updateCallbacks;
@@ -1679,11 +2157,12 @@ declare class MemoryAdapter implements StorageAdapter {
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
 }
 
-declare function createUpdateStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<Update<T>>;
-declare function createEntityStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
-declare function createRichUpdateStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<RichUpdate<T>>;
+declare function createUpdateStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, keyFilter?: string, snapshotEnabled?: boolean): AsyncIterable<Update<T>>;
+declare function createEntityStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
+declare function createRichUpdateStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, keyFilter?: string, snapshotEnabled?: boolean): AsyncIterable<RichUpdate<T>>;
 
-declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T>;
+declare function serializeViewKey<TKey>(viewDef: ViewDef<unknown, 'state', TKey>, key: TKey): string;
+declare function createTypedStateView<T, TKey = unknown>(viewDef: ViewDef<T, 'state', TKey>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T, DefaultViewKey<TKey>>;
 declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
 declare function createTypedViews<TStack extends StackDefinition>(stack: TStack, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedViews<TStack['views']>;
 
@@ -1691,5 +2170,5 @@ declare const Arete: typeof Arete$1 & {
     session: typeof createSession;
 };
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, instructionOperation, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, literal, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, serializeInstructionData, stackQuery, toJsonValue, toRawAmount, transactionOperation, validateAccountResolution, withPrograms };
-export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenResult, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ConfirmationLevel, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, MergeProgramMaps, MintAccountInfo, NonEmptyReadonlyArray, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationKind, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramsInterface, QueriesInterface, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadTransportMethod, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TokenAccountInfo, TokenBalanceInfo, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewDef, ViewGroup, ViewSortConfig, WalletAdapter, WalletConnectOptions, WalletState, WatchOptions, WebSocketFactoryInit };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TransactionExecutionError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, safeToRawAmount, serializeInstructionData, serializeViewKey, stackQuery, stringifyBigints, toJsonValue, toRawAmount, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateSubscriptionId, withPrograms };
+export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, ConfirmationLevel, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOutcome, TransactionRequestContext, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };