@usearete/sdk 0.24.0 → 0.25.1

package/dist/index.d.ts

@@ -751,15 +751,15 @@ declare function createInstructionHandler<TParams = Record<string, unknown>, TEr
  */
 interface BuildOptions {
     /** Wallet, used only for accounts explicitly marked with signerKind: 'wallet'. */
-    wallet?: WalletAdapter;
+    wallet?: WalletAdapter | undefined;
     /** Explicit account-address overrides, including signer slots when needed. */
-    accounts?: Record<string, string>;
+    accounts?: Record<string, string> | undefined;
     /**
      * Extra account metas appended after the instruction's declared accounts
      * (Anchor's `remainingAccounts`) — for routers, transfer hooks, and other
      * composition patterns the IDL cannot express.
      */
-    remainingAccounts?: BuiltAccountMeta[];
+    remainingAccounts?: BuiltAccountMeta[] | undefined;
 }
 /**
  * Options for executing (building + sending) an instruction.
@@ -954,6 +954,17 @@ interface ProgramSdkDefinition {
     readonly programId?: string;
     /** Typed identity of generated program content. V2 excludes compiler provenance. */
     readonly sdkDefinitionHash?: string;
+    /**
+     * Program package release this SDK was generated from, for program SDKs
+     * installed from the registry. It is the program SDK's identity: a stack's
+     * embedded program and a standalone install with the same value are the same
+     * program, and the SDK runtime treats them as one when both are attached.
+     * Generated entries stamp it with `withProgramIdentity` after applying the
+     * package's own extension; `extendProgram`, `extendPrograms` and
+     * `withProgramRead` drop it, because a program changed outside its generated
+     * SDK is no longer provably that SDK.
+     */
+    readonly packageReleaseHash?: string;
     readonly programSpecHash?: string;
     readonly idlContentHash?: string;
     readonly normalizedIdlHash?: string;
@@ -1152,6 +1163,14 @@ interface WatchOptions<TSchema = unknown> {
     /** Maximum number of entities to include in snapshot */
     snapshotLimit?: number;
 }
+/** Options for the one-shot reads `get` and `getOne`. */
+interface GetOptions extends WatchOptions {
+    /**
+     * How long to wait for the initial snapshot before rejecting with
+     * `InitialDataTimeoutError` (defaults to 5000). `null` waits forever.
+     */
+    timeoutMs?: number | null;
+}
 interface AreteOptions<TStack extends StackDefinition> {
     stack: TStack;
     /** Connect immediately when the client is created (defaults to true). */
@@ -1230,6 +1249,13 @@ interface AreteConfig {
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     initialSubscriptions?: Subscription[];
+    /**
+     * Entities kept per view; the oldest are dropped past it. `null` keeps all.
+     * Keep it above the size of every subscription on a view: the server still
+     * counts a dropped entity as held and sends only patches for it, which are
+     * discarded (reported as `'evicted-key'` diagnostics), so it stays missing
+     * until it re-enters the query or the subscription is re-established.
+     */
     maxEntriesPerView?: number | null;
     /** Authentication configuration */
     auth?: AuthConfig;
@@ -1310,14 +1336,32 @@ 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>;
+    /**
+     * Open (or reuse) the equivalent subscription, wait for its initial
+     * snapshot, and release it. Resolves `null` when the entity is absent.
+     */
+    get(key: TKey, options?: GetOptions): Promise<T | null>;
+    /**
+     * Read an already active equivalent subscription without waiting;
+     * `undefined` when none is active (absent is not the same as empty).
+     */
     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(options?: WatchOptions): Promise<T[]>;
+    /**
+     * Open (or reuse) the equivalent subscription, wait for its initial
+     * snapshot, and release it.
+     */
+    get(options?: GetOptions): Promise<T[]>;
+    /** Like `get` with `take: 1`: the first item, or `null` when the list is empty. */
+    getOne(options?: Omit<GetOptions, 'take'>): Promise<T | null>;
+    /**
+     * Read an already active equivalent subscription without waiting;
+     * `undefined` when none is active (absent is not the same as empty).
+     */
     getSync(options?: WatchOptions): T[] | undefined;
 }
 type SubscribeCallback<T> = (update: Update<T>) => void;
@@ -1356,6 +1400,12 @@ interface SubscribedFrame extends IdentifiedFrame {
     sort?: SortConfig;
     /** Present on append views backed by the journal. */
     replayWindow?: ReplayWindow;
+    /**
+     * The server sends a key whole (`upsert` or a snapshot row) before any
+     * `patch` for it, so a patch for a key the client does not hold can be
+     * dropped. Older servers omit it; their patches for unknown keys are kept.
+     */
+    wholeEntities?: boolean;
 }
 interface UnsubscribedFrame extends IdentifiedFrame {
     op: 'unsubscribed';
@@ -1625,6 +1675,11 @@ declare class ProcessedSlotTimeoutError extends Error {
     constructor(targetSlot: bigint, processedSlot: bigint | null);
 }
 interface FrameProcessorConfig {
+    /**
+     * Entities kept per view (see `AreteConfig.maxEntriesPerView`). Keep it
+     * above every subscription's size: patches for an entity dropped here are
+     * discarded until the server sends it whole again.
+     */
     maxEntriesPerView?: number | null;
     /**
      * Interval in milliseconds to buffer frames before flushing to storage.
@@ -1638,9 +1693,13 @@ interface FrameProcessorConfig {
     schemas?: Record<string, Schema<unknown>>;
     patchSchemas?: Record<string, Schema<unknown>>;
     queryStore?: QueryStore;
-    /** Whether rejected frames should also be written to `console.warn`. */
+    /** Whether schema-rejected frames should also be written to `console.warn`. */
     warnOnValidationError?: boolean;
-    /** Receives structured details whenever a generated schema rejects a frame. */
+    /**
+     * Receives structured details whenever a frame is not stored: a generated
+     * schema rejected it, or it was a `patch` for a key the client holds no
+     * entity for.
+     */
     onValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
 }
 interface FrameValidationDiagnostic {
@@ -1648,6 +1707,25 @@ interface FrameValidationDiagnostic {
     readonly key?: string;
     readonly seq?: string;
     readonly operation: 'snapshot' | 'upsert' | 'patch';
+    /**
+     * Why the frame was not stored. `'schema'`: a generated schema rejected it.
+     * `'unknown-key'`: a `patch` for a key the client never received. A patch
+     * is a partial entity, so it is discarded; the entity appears when the
+     * server sends a full `upsert` for the key. `'evicted-key'`: a `patch` for a
+     * key this client dropped to stay within `maxEntriesPerView`. The server
+     * still counts the client as holding it, so it keeps sending patches and
+     * sends no `upsert` until the key re-enters the query or the subscription
+     * is re-established; raise `maxEntriesPerView` above the subscription's
+     * size to avoid this.
+     *
+     * Patches are discarded only when the server's `subscribed` acknowledgement
+     * carries `wholeEntities: true`; with an older server a patch for an unknown
+     * key is stored as the entity, as before. Replayable append-view records
+     * (frames with an `offset`) are events and are never discarded this way.
+     * `'schema'` diagnostics, and the first `'evicted-key'` one per view, are
+     * written to `console.warn` when `warnOnValidationError` is on.
+     */
+    readonly reason: 'schema' | 'unknown-key' | 'evicted-key';
     readonly error: unknown;
 }
 declare class FrameProcessor {
@@ -1665,6 +1743,15 @@ declare class FrameProcessor {
     private latestProcessedSlot;
     private processedSlotWaiters;
     private cursors;
+    /**
+     * Whether the server's latest acknowledgement guaranteed whole entities.
+     * One connection talks to one server, so its latest ack speaks for every
+     * subscription on it; a reconnect re-acknowledges each one.
+     */
+    private serverSendsWholeEntities;
+    /** Keys dropped by `maxEntriesPerView`, per view, oldest first; bounded. */
+    private evictedKeys;
+    private warnedEvictedViews;
     /**
      * Observe the connection's cursor tracker instead of a private one.
      *
@@ -1676,6 +1763,7 @@ declare class FrameProcessor {
     constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
     private getSchema;
     private normalizeEntity;
+    private reportDiagnostic;
     private hasSchema;
     private normalizePathSegment;
     private normalizePath;
@@ -1684,6 +1772,17 @@ declare class FrameProcessor {
     private extractSeq;
     private getInternalSeq;
     private compareSeq;
+    private extractVersion;
+    private getInternalVersion;
+    /**
+     * Whether a frame at `incoming` is one this client already applied, or older.
+     * A version is `{epoch}:{counter}`, and counters compare only within an
+     * epoch: a server restart or a reloaded stack starts a new one, whose first
+     * frame is newer than anything from the old one. A version that does not
+     * parse cannot be ordered and is never stale.
+     */
+    private isStaleVersion;
+    private attachInternalVersion;
     private attachInternalSeq;
     handleFrame<T>(frame: Frame<T>): void;
     /**
@@ -1715,6 +1814,13 @@ declare class FrameProcessor {
     private emitRichUpdate;
     private createRichUpdate;
     private enforceMaxEntries;
+    /**
+     * Remember a key `maxEntriesPerView` dropped, so a later patch for it can be
+     * reported as such. At most `limit` keys per view, most recent kept.
+     */
+    private rememberEvicted;
+    private forgetEvicted;
+    private reportDiscardedPatch;
 }
 
 interface NormalizedSubscriptionRequest {
@@ -1732,6 +1838,8 @@ declare class SubscriptionRegistry {
     private readonly queryStore;
     private readonly subscriptions;
     private readonly subscriptionsById;
+    private readonly failureListeners;
+    private connectionError;
     constructor(connection: ConnectionManager, queryStore: QueryStore);
     subscribe(query: SubscriptionQuery, snapshotEnabled?: boolean): QueryLease;
     refresh(query: SubscriptionQuery, snapshotEnabled?: boolean): Promise<void>;
@@ -1744,8 +1852,16 @@ declare class SubscriptionRegistry {
     getRefCount(query: SubscriptionQuery, snapshotEnabled?: boolean): number;
     getActiveSubscriptions(): Subscription[];
     getSnapshot<T>(query: SubscriptionQuery, snapshotEnabled?: boolean): QuerySnapshot<T> | undefined;
-    handleConnectionState(state: ConnectionState): void;
+    handleConnectionState(state: ConnectionState, message?: string): void;
+    /** The terminal connection failure while the connection is in the `error` state. */
+    getConnectionError(): AreteError | undefined;
+    /**
+     * Called when pending queries can no longer resolve: the connection failed
+     * terminally, or a disconnect cleared every subscription.
+     */
+    onFailure(callback: (error: AreteError) => void): UnsubscribeFn;
     clear(): void;
+    private notifyFailure;
     private createLease;
     private getTracker;
     private refreshTracker;
@@ -1904,18 +2020,18 @@ interface CreatePreparedInstructionInput<TArtifacts> {
     name: string;
     instruction: BuiltInstruction;
     artifacts: TArtifacts;
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }
 type PreparedTransactionInstruction = BuiltInstruction | PreparedInstruction<unknown>;
 type PreparedTransactionOperation = PreparedInstruction<unknown> | PreparedTransaction<unknown>;
 interface CreatePreparedTransactionBaseInput<TArtifacts> {
     name: string;
     artifacts: TArtifacts;
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }
 type CreatePreparedTransactionInput<TArtifacts> = CreatePreparedTransactionBaseInput<TArtifacts> & ({
     instructions: readonly PreparedTransactionInstruction[];
@@ -1932,9 +2048,9 @@ interface CreatePreparedFlowInput<TArtifacts> {
 declare function createPreparedTransactionBody(input: {
     name: string;
     instructions: readonly BuiltInstruction[];
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }): PreparedTransactionBody;
 declare function createPreparedInstruction<TArtifacts>(input: CreatePreparedInstructionInput<TArtifacts>): PreparedInstruction<TArtifacts>;
 declare function createPreparedTransaction<TArtifacts>(input: CreatePreparedTransactionInput<TArtifacts>): PreparedTransaction<TArtifacts>;
@@ -2075,6 +2191,34 @@ declare function instructionOperation<TInput, TArtifacts>(prepare: (input: TInpu
 declare function transactionOperation<TInput, TArtifacts>(prepare: (input: TInput) => MaybePromise<PreparedTransaction<TArtifacts>>): TransactionOperation<TInput, TArtifacts>;
 declare function flowOperation<TInput, TArtifacts>(prepare: (input: TInput) => MaybePromise<PreparedFlow<TArtifacts>>): FlowOperation<TInput, TArtifacts>;
 
+/**
+ * Version of the extension contract: `defineStackExtensions`,
+ * `defineProgramExtensions`, `extendProgram`, `extendPrograms`, `extendStack`,
+ * `withProgramRead`, and the instruction helpers generated code imports
+ * (`createInstructionHandler`, `buildInstruction`, `instructionOperation`,
+ * `createPreparedInstruction`, the PDA and read helpers, …).
+ *
+ * It only changes on a breaking change to that contract, so generated SDKs and
+ * extensions built for one value keep working with every SDK release that
+ * exports the same value. The same number is published in this package's
+ * `package.json` as `arete.extensionApi` for tools that read `node_modules`.
+ */
+declare const EXTENSION_API_VERSION: 1;
+/**
+ * Runtime extension carriers live under registry symbols (`Symbol.for`), so
+ * two copies of this module still read each other's definitions. The
+ * properties are enumerable: `{ ...stack }` and `{ ...program }` keep them,
+ * while `Object.keys`, `for…in` and `JSON.stringify` never see a symbol key.
+ *
+ * The constants are typed as their historical property names rather than as
+ * `unique symbol`. Generated program SDKs use them as computed keys inside
+ * object literals, and TypeScript can only name a `unique symbol` key in
+ * emitted declarations from a file that imports it; a string-literal key type
+ * keeps every generated `.d.ts` nameable and identical across module copies.
+ * Always read and write these properties through the constants (or
+ * `getStackRuntimeExtensions` / `getProgramRuntimeExtensions`), never by the
+ * literal name.
+ */
 declare const STACK_RUNTIME_EXTENSIONS: "__areteStackRuntimeExtensions";
 declare const PROGRAM_OPERATION_EXTENSIONS: "__areteProgramOperationExtensions";
 type EmptyRecord = Record<string, never>;
@@ -2092,6 +2236,13 @@ type MaybeField<TKey extends string, TValue> = [TValue] extends [never] ? {} : {
     readonly [K in TKey]: TValue;
 };
 type Field<TValue, TKey extends PropertyKey> = TKey extends keyof TValue ? TValue[TKey] : never;
+/**
+ * A field an extension provides. The helpers skip an extension value that is
+ * `undefined`, so an optional field is never `undefined` on the result either
+ * (which `exactOptionalPropertyTypes` would reject where the result is used as
+ * a `ProgramSdkDefinition`).
+ */
+type ExtensionField<TValue, TKey extends PropertyKey> = Exclude<Field<TValue, TKey>, undefined>;
 type DeepMerge<TBase, TExtension> = TBase extends Record<string, unknown> ? TExtension extends Record<string, unknown> ? Omit<TBase, keyof TExtension> & {
     readonly [K in keyof TExtension]: K extends keyof TBase ? DeepMerge<TBase[K], TExtension[K]> : TExtension[K];
 } : TExtension : TExtension;
@@ -2143,7 +2294,7 @@ type DefinedProgramExtensions<TBase extends ProgramSdkDefinition, TAddresses, TC
     readonly createRead?: (context: ProgramOperationContext<ExtendedProgramDefinition<TBase, TAddresses, TConstants, TDefaults, ProgramOperations, TMath, never>>) => TRead;
 };
 declare function defineProgramExtensions<TBase extends ProgramSdkDefinition>(): <TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never, TRead = never>(extensions: DefinedProgramExtensions<TBase, TAddresses, TConstants, TDefaults, TOperations, TMath, TRead>) => DefinedProgramExtensions<TBase, TAddresses, TConstants, TDefaults, TOperations, TMath, TRead>;
-declare function extendProgram<TBase extends ProgramSdkDefinition, TExtension extends ProgramExtensionInput<any, any, any, any, any, any, any>>(program: TBase, extensions: TExtension): ExtendedProgramDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, Extract<FactoryReturn<TExtension, 'createOperations'>, AnyProgramOperations>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, FactoryReturn<TExtension, 'createRead'>>;
+declare function extendProgram<TBase extends ProgramSdkDefinition, TExtension extends ProgramExtensionInput<any, any, any, any, any, any, any>>(program: TBase, extensions: TExtension): ExtendedProgramDefinition<TBase, MergeField<Field<TBase, 'addresses'>, ExtensionField<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, ExtensionField<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, ExtensionField<TExtension, 'defaults'>>, Extract<FactoryReturn<TExtension, 'createOperations'>, AnyProgramOperations>, MergeField<Field<TBase, 'math'>, ExtensionField<TExtension, 'math'>>, FactoryReturn<TExtension, 'createRead'>>;
 declare function extendPrograms<TPrograms extends Record<string, ProgramSdkDefinition>, TExtensions extends Partial<{
     [K in keyof TPrograms]: ProgramExtensionInput<any, any, any, any, any, any, any>;
 }>>(programs: TPrograms, extensions: TExtensions): {
@@ -2182,13 +2333,29 @@ declare function defineStackExtensions<TBase extends StackDefinition>(): <const
     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 & 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 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'>, ExtensionField<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, ExtensionField<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, ExtensionField<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, ExtensionField<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>;
 type NormalizeProgramMap<TPrograms> = TPrograms extends ProgramMap ? TPrograms : Record<string, never>;
-type MergeProgramMaps<TStackPrograms, TAttachedPrograms> = Omit<NormalizeProgramMap<TAttachedPrograms>, keyof NormalizeProgramMap<TStackPrograms>> & NormalizeProgramMap<TStackPrograms>;
+/**
+ * The keys a program map names, leaving out an index signature. `keyof` of
+ * `Record<string, never>` (nothing attached) or of a wide
+ * `Record<string, ProgramSdkDefinition>` is `string`, which would omit every
+ * program a stack provides.
+ */
+type NamedProgramKeys<TPrograms> = keyof {
+    [K in keyof TPrograms as string extends K ? never : number extends K ? never : K]: unknown;
+};
+/**
+ * A stack's programs with attached programs added. An attached program under a
+ * key the stack provides takes that key: it is either the same program SDK
+ * (identical at runtime) or one with the same program spec that could not be
+ * proven identical, which the runtime uses in place of the stack's. Keys the
+ * attached map does not name keep the stack's program types.
+ */
+type MergeProgramMaps<TStackPrograms, TAttachedPrograms> = Omit<NormalizeProgramMap<TStackPrograms>, NamedProgramKeys<NormalizeProgramMap<TAttachedPrograms>>> & NormalizeProgramMap<TAttachedPrograms>;
 type StackWithAttachedPrograms<TStack extends StackDefinition, TAttachedPrograms extends ProgramMap | undefined> = Omit<TStack, 'programs'> & {
     programs: MergeProgramMaps<TStack['programs'], TAttachedPrograms>;
 };
@@ -2226,7 +2393,13 @@ interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined, T
     wallet?: WalletAdapter;
     /** Optional fetch implementation for HTTP point reads. */
     fetch?: typeof fetch;
-    /** Additional program SDKs exposed under client.programs.<key>. */
+    /**
+     * Additional program SDKs exposed under client.programs.<key>. Under a key
+     * the stack already provides, the same program SDK (the same object or the
+     * same `packageReleaseHash`) resolves to the stack's; a program with the
+     * same `programSpecHash` that cannot be proven identical replaces it, with a
+     * warning; anything else throws `PROGRAM_KEY_CONFLICT`.
+     */
     programs?: TPrograms;
     /** Per-program complete descriptor replacements. */
     programReads?: ProgramReadOverrides<MergeProgramMaps<TStackPrograms, TPrograms>>;
@@ -2419,6 +2592,17 @@ declare class Arete$1<TStack extends StackDefinition> {
 interface SessionDefinition<TPrograms extends Record<string, ProgramSdkDefinition> = Record<string, ProgramSdkDefinition>> {
     readonly mode?: 'composition';
     readonly stacks?: Record<string, StackDefinition>;
+    /**
+     * Standalone program SDKs, available at `session.programs.<key>`. Under a key
+     * a stack also provides, the same program SDK (the same object or the same
+     * `packageReleaseHash`) is served from the stack's connected instance, unless
+     * this definition's `programReads.<key>` resolves to a descriptor other than
+     * the one the stack reads through. That program, or one with the same
+     * `programSpecHash` that cannot be proven identical, takes
+     * `session.programs.<key>` with its own read configuration, with a warning,
+     * while `session.stacks.<stack>.programs.<key>` keeps the stack's; anything
+     * else throws `PROGRAM_KEY_CONFLICT`.
+     */
     readonly programs?: TPrograms;
     /** Hosted chain and transaction capabilities shared by a generated composition. */
     readonly gateway?: HostedSolanaGatewayBindings;
@@ -2526,10 +2710,57 @@ declare function createSession<TDef extends SessionDefinition, TStackPrograms ex
 /**
  * Bundle a generated program definition with its default read descriptor.
  *
- * Generated SDK entries call this automatically. The descriptor is deliberately
- * non-enumerable so it remains an implementation detail of the program cartridge.
+ * Generated SDK entries call this automatically. The descriptor lives under a
+ * registry symbol, so `Object.keys` and `JSON.stringify` never see it, while
+ * `{ ...program }` keeps it: a spread program still reads through its release.
+ * Every other own property (including the runtime extension carrier) is copied
+ * unchanged, except `packageReleaseHash`: the result reads differently from
+ * the generated program SDK, so it is no longer provably that SDK. Generated
+ * entries apply `withProgramIdentity` last.
  */
 declare function withProgramRead<TProgram extends ProgramSdkDefinition>(program: TProgram, descriptor: ProgramReadDescriptor): TProgram;
+/** The identity a generated program SDK entry stamps on its final program. */
+interface ProgramSdkIdentity {
+    /** The program package release the SDK was generated from, when known. */
+    readonly packageReleaseHash?: string;
+}
+/**
+ * Stamp a program definition with the identity of the program SDK it is.
+ *
+ * Generated program SDK entries call this last, after the package's own
+ * extension and read descriptor are applied, so the identity describes
+ * exactly the generated SDK. `extendProgram`, `extendPrograms` and
+ * `withProgramRead` drop the identity again: a program changed outside its
+ * generated SDK is no longer provably that SDK. Every other own property,
+ * including symbol-keyed runtime extensions and the read descriptor, is copied
+ * unchanged. An absent or empty `packageReleaseHash` removes the identity.
+ */
+declare function withProgramIdentity<TProgram extends ProgramSdkDefinition>(program: TProgram, identity: ProgramSdkIdentity): TProgram;
+
+/** Error code for two different program SDKs claiming one program key. */
+declare const PROGRAM_KEY_CONFLICT: "PROGRAM_KEY_CONFLICT";
+/**
+ * How two program definitions under one key relate:
+ *
+ * - `'same'`: the same program SDK. They are the same object, or both carry a
+ *   `packageReleaseHash` and the hashes are equal.
+ * - `'unproven'`: at least one has no `packageReleaseHash` (a local build, or
+ *   a program extended outside its generated SDK), but both carry the same
+ *   `programSpecHash`. They describe the same program but cannot be proven to
+ *   be the same SDK.
+ * - `'different'`: both carry a `packageReleaseHash` and the hashes differ, or
+ *   neither identity matches (different or missing `programSpecHash`).
+ */
+type ProgramIdentityMatch = 'same' | 'unproven' | 'different';
+/** Compare two program definitions by identity, never by name. */
+declare function compareProgramIdentity(left: ProgramSdkDefinition, right: ProgramSdkDefinition): ProgramIdentityMatch;
+/**
+ * Whether two program definitions are provably the same program SDK: the same
+ * object, or both carry the same `packageReleaseHash` (the program package
+ * release they were generated from). Anything else is not provably the same,
+ * even under the same name.
+ */
+declare function isSameProgramSdk(left: ProgramSdkDefinition, right: ProgramSdkDefinition): boolean;
 
 /**
  * Non-enumerable brand attached by the operation and read factories so
@@ -2585,7 +2816,8 @@ type AmountInput = bigint | {
 interface AmountResolutionInput {
     mint: string;
     amount: AmountInput;
-    decimals?: number;
+    /** The mint's decimals; read from the mint when absent. */
+    decimals?: number | undefined;
 }
 /** Convert a UI amount ("1.5") to raw base units using string math (no float precision loss). */
 declare function parseUiAmountToRaw(value: string | number, decimals: number): bigint;
@@ -2715,6 +2947,18 @@ declare function createUpdateStream<T>(_storage: StorageAdapter, subscriptionReg
 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>>;
 
+/** How long `get` and `getOne` wait for an initial snapshot, as in the Rust and Python SDKs. */
+declare const DEFAULT_INITIAL_DATA_TIMEOUT_MS = 5000;
+/**
+ * `get` or `getOne` gave up waiting for the initial snapshot: the socket never
+ * delivered it (no connection, a reconnect storm, a server that never
+ * answers). The read's subscription is released before this is thrown.
+ */
+declare class InitialDataTimeoutError extends AreteError {
+    readonly view: string;
+    readonly timeoutMs: number;
+    constructor(view: string, timeoutMs: number);
+}
 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>;
@@ -2724,5 +2968,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, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, 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, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramRead, withPrograms };
-export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, 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, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, 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, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
+export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, 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, GetOptions, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramIdentityMatch, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramSdkIdentity, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };