@usearete/sdk 0.24.0 → 0.25.1

package/dist/index.esm.js

@@ -442,6 +442,7 @@ class SubscriptionRegistry {
         this.queryStore = queryStore;
         this.subscriptions = new Map();
         this.subscriptionsById = new Map();
+        this.failureListeners = new Set();
     }
     subscribe(query, snapshotEnabled = true) {
         const request = normalizeSubscriptionRequest({
@@ -504,12 +505,30 @@ class SubscriptionRegistry {
             ? this.queryStore.getSnapshot(tracker.subscription.subscriptionId)
             : undefined;
     }
-    handleConnectionState(state) {
+    handleConnectionState(state, message) {
         if (state === 'reconnecting')
             this.queryStore.beginReconnect();
-        if (state === 'error') {
-            this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        if (state !== 'error') {
+            this.connectionError = undefined;
+            return;
         }
+        this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        // Queries still waiting for their first snapshot are not failed above;
+        // one-shot reads learn about the failure here instead of timing out.
+        this.connectionError = new AreteError(message ?? 'Connection failed', 'CONNECTION_ERROR');
+        this.notifyFailure(this.connectionError);
+    }
+    /** The terminal connection failure while the connection is in the `error` state. */
+    getConnectionError() {
+        return this.connectionError;
+    }
+    /**
+     * Called when pending queries can no longer resolve: the connection failed
+     * terminally, or a disconnect cleared every subscription.
+     */
+    onFailure(callback) {
+        this.failureListeners.add(callback);
+        return () => this.failureListeners.delete(callback);
     }
     clear() {
         for (const { subscription } of this.subscriptions.values()) {
@@ -525,6 +544,11 @@ class SubscriptionRegistry {
         }
         this.subscriptions.clear();
         this.subscriptionsById.clear();
+        this.notifyFailure(new AreteError('Subscriptions were cleared by a disconnect', 'CONNECTION_CANCELLED'));
+    }
+    notifyFailure(error) {
+        for (const listener of [...this.failureListeners])
+            listener(error);
     }
     createLease(tracker) {
         let released = false;
@@ -1872,6 +1896,7 @@ class ConnectionManager {
 }
 
 const INTERNAL_SEQ_FIELD = '__seq';
+const INTERNAL_VERSION_FIELD = '__version';
 class ProcessedSlotTimeoutError extends Error {
     constructor(targetSlot, processedSlot) {
         super(`Timed out waiting for Arete to process slot ${targetSlot}`);
@@ -1932,6 +1957,9 @@ function toCamelCaseSegment(value) {
     if (value === '_seq') {
         return INTERNAL_SEQ_FIELD;
     }
+    if (value === '_version') {
+        return INTERNAL_VERSION_FIELD;
+    }
     const pascal = value
         .split(/[_.-]/)
         .filter(segment => segment.length > 0)
@@ -1942,6 +1970,16 @@ function toCamelCaseSegment(value) {
     }
     return pascal[0].toLowerCase() + pascal.slice(1);
 }
+/** `{epoch}:{counter}` from a frame's `_version`, or null if it does not parse. */
+function parseVersion(version) {
+    const separator = version.lastIndexOf(':');
+    if (separator <= 0)
+        return null;
+    const counter = version.slice(separator + 1);
+    if (!/^\d+$/.test(counter))
+        return null;
+    return { epoch: version.slice(0, separator), counter: BigInt(counter) };
+}
 class FrameProcessor {
     /**
      * Observe the connection's cursor tracker instead of a private one.
@@ -1960,6 +1998,15 @@ class FrameProcessor {
         this.latestProcessedSlot = null;
         this.processedSlotWaiters = new Set();
         this.cursors = new CursorTracker();
+        /**
+         * 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.
+         */
+        this.serverSendsWholeEntities = false;
+        /** Keys dropped by `maxEntriesPerView`, per view, oldest first; bounded. */
+        this.evictedKeys = new Map();
+        this.warnedEvictedViews = new Set();
         this.storage = storage;
         this.maxEntriesPerView = config.maxEntriesPerView === undefined
             ? DEFAULT_MAX_ENTRIES_PER_VIEW
@@ -2007,18 +2054,22 @@ class FrameProcessor {
         const diagnostic = {
             view: viewPath,
             ...context,
+            reason: 'schema',
             error: validationError,
         };
+        this.reportDiagnostic(diagnostic);
+        if (this.warnOnValidationError) {
+            console.warn('[Arete] Frame validation failed:', diagnostic);
+        }
+        return null;
+    }
+    reportDiagnostic(diagnostic) {
         try {
             this.onValidationError?.(diagnostic);
         }
         catch (callbackError) {
             console.error('[Arete] Frame validation callback failed:', callbackError);
         }
-        if (this.warnOnValidationError) {
-            console.warn('[Arete] Frame validation failed:', diagnostic);
-        }
-        return null;
     }
     hasSchema(viewPath) {
         return this.getSchema(viewPath) !== null;
@@ -2085,6 +2136,50 @@ class FrameProcessor {
         }
         return leftIndex.localeCompare(rightIndex);
     }
+    extractVersion(data) {
+        if (!isObject(data)) {
+            return undefined;
+        }
+        const version = data._version;
+        return typeof version === 'string' ? version : undefined;
+    }
+    getInternalVersion(data) {
+        if (!isObject(data)) {
+            return undefined;
+        }
+        const version = data[INTERNAL_VERSION_FIELD];
+        return typeof version === 'string' ? version : undefined;
+    }
+    /**
+     * 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.
+     */
+    isStaleVersion(incoming, held) {
+        if (held === undefined) {
+            return false;
+        }
+        const next = parseVersion(incoming);
+        const current = parseVersion(held);
+        if (next === null || current === null || next.epoch !== current.epoch) {
+            return false;
+        }
+        return next.counter <= current.counter;
+    }
+    attachInternalVersion(data, version) {
+        if (!version || !isObject(data)) {
+            return data;
+        }
+        Object.defineProperty(data, INTERNAL_VERSION_FIELD, {
+            value: version,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+        return data;
+    }
     attachInternalSeq(_viewPath, data, seq) {
         if (!seq || !isObject(data)) {
             return data;
@@ -2305,6 +2400,7 @@ class FrameProcessor {
     }
     handleSubscribedFrame(frame) {
         this.cursors.observe(frame);
+        this.serverSendsWholeEntities = frame.wholeEntities === true;
         const viewPath = frame.query.view;
         if (this.storage.setViewConfig && frame.sort) {
             this.storage.setViewConfig(viewPath, {
@@ -2329,10 +2425,11 @@ class FrameProcessor {
             if (normalized === null) {
                 continue;
             }
-            const nextValue = this.attachInternalSeq(viewPath, normalized, this.extractSeq(entity.data));
+            const nextValue = this.attachInternalVersion(this.attachInternalSeq(viewPath, normalized, this.extractSeq(entity.data)), this.extractVersion(entity.data));
             acceptedKeys.push(entity.key);
             const previousValue = this.storage.get(viewPath, entity.key);
             this.storage.set(viewPath, entity.key, nextValue);
+            this.forgetEvicted(viewPath, entity.key);
             this.storage.notifyUpdate(viewPath, entity.key, {
                 type: 'upsert',
                 key: entity.key,
@@ -2351,18 +2448,24 @@ class FrameProcessor {
         const previousValue = this.storage.get(viewPath, frame.key);
         const previousSequence = this.getInternalSeq(previousValue);
         const cursor = this.cursors.observe(frame);
-        // On a tape the offset is the identity: two events decoded from one
-        // transaction share a seq, so the seq guard would discard the second.
-        const duplicateOrStaleSequence = frame.offset === undefined
-            && frame.seq !== undefined
-            && previousSequence !== undefined
-            && this.compareSeq(frame.seq, previousSequence) <= 0;
+        // A server that stamps `_version` orders one key's frames by it. `seq`
+        // cannot: every update decoded from one transaction shares one, and within
+        // a slot account updates and instructions number themselves differently,
+        // so a later frame can carry a lower `seq`. Without a version (an older
+        // server) the `seq` rule applies. On a tape the offset is the identity, so
+        // neither does.
+        const frameVersion = this.extractVersion(frame.data);
+        const duplicateOrStale = frame.offset === undefined && (frameVersion !== undefined
+            ? this.isStaleVersion(frameVersion, this.getInternalVersion(previousValue))
+            : frame.seq !== undefined
+                && previousSequence !== undefined
+                && this.compareSeq(frame.seq, previousSequence) <= 0);
         switch (frame.op) {
             case 'upsert':
                 {
                     if (frame.data === null)
                         break;
-                    if (duplicateOrStaleSequence && previousValue !== null) {
+                    if (duplicateOrStale && previousValue !== null) {
                         const update = {
                             type: 'upsert',
                             key: frame.key,
@@ -2379,14 +2482,17 @@ class FrameProcessor {
                     if (normalized === null) {
                         break;
                     }
-                    const nextValue = this.attachInternalSeq(viewPath, normalized, 
+                    const nextValue = this.attachInternalVersion(this.attachInternalSeq(viewPath, normalized, 
                     // Fall back to the previous entity's sequence, as the patch branch
                     // below does. Without this an unsequenced upsert drops the tracked
                     // sequence (it rides on the object being replaced), disarming the
                     // staleness guard until the next sequenced frame and letting a
                     // later older frame overwrite newer data.
-                    frame.seq ?? this.extractSeq(frame.data) ?? this.getInternalSeq(previousValue));
+                    frame.seq ?? this.extractSeq(frame.data) ?? this.getInternalSeq(previousValue)), 
+                    // An unversioned write keeps the version it replaces, likewise.
+                    frameVersion ?? this.getInternalVersion(previousValue));
                     this.storage.set(viewPath, frame.key, nextValue);
+                    this.forgetEvicted(viewPath, frame.key);
                     const update = {
                         type: 'upsert',
                         key: frame.key,
@@ -2403,6 +2509,19 @@ class FrameProcessor {
                 if (frame.data === null)
                     break;
                 const existing = this.storage.get(viewPath, frame.key);
+                if (existing === null && frame.offset === undefined && this.serverSendsWholeEntities) {
+                    // A patch carries only changed fields. With no entity to merge into
+                    // (never received, or evicted) it would be stored as a partial
+                    // entity typed as complete, so it is discarded: no storage write, no
+                    // sequence, no query membership, no update. The key appears when the
+                    // server sends a full upsert, which a server acknowledging
+                    // `wholeEntities` guarantees for every key it has not sent. Tape
+                    // records (frames with an `offset`) are events rather than entity
+                    // state and are always applied: a consumer resuming from a cursor
+                    // holds what came before it.
+                    this.reportDiscardedPatch(viewPath, frame);
+                    break;
+                }
                 const normalizedPatch = this.normalizeEntity(viewPath, frame.data, {
                     key: frame.key,
                     operation: 'patch',
@@ -2411,7 +2530,7 @@ class FrameProcessor {
                 if (normalizedPatch === null) {
                     break;
                 }
-                if (duplicateOrStaleSequence && existing !== null) {
+                if (duplicateOrStale && existing !== null) {
                     const update = {
                         type: 'patch',
                         key: frame.key,
@@ -2424,7 +2543,7 @@ class FrameProcessor {
                 const merged = existing
                     ? deepMergeWithAppend(existing, normalizedPatch, appendPaths)
                     : normalizedPatch;
-                const nextValue = this.attachInternalSeq(viewPath, merged, frame.seq ?? this.extractSeq(frame.data) ?? this.getInternalSeq(existing));
+                const nextValue = this.attachInternalVersion(this.attachInternalSeq(viewPath, merged, frame.seq ?? this.extractSeq(frame.data) ?? this.getInternalSeq(existing)), frameVersion ?? this.getInternalVersion(existing));
                 this.storage.set(viewPath, frame.key, nextValue);
                 const update = {
                     type: 'patch',
@@ -2443,6 +2562,7 @@ class FrameProcessor {
                 break;
             case 'delete':
                 this.storage.delete(viewPath, frame.key);
+                this.forgetEvicted(viewPath, frame.key);
                 this.storage.notifyUpdate(viewPath, frame.key, {
                     type: 'delete',
                     key: frame.key,
@@ -2479,8 +2599,56 @@ class FrameProcessor {
             return;
         while (this.storage.size(viewPath) > this.maxEntriesPerView) {
             const evicted = this.storage.evictOldest(viewPath);
-            if (evicted !== undefined)
-                this.queryStore?.evict(viewPath, evicted);
+            if (evicted === undefined)
+                continue;
+            this.queryStore?.evict(viewPath, evicted);
+            this.rememberEvicted(viewPath, evicted, this.maxEntriesPerView);
+        }
+    }
+    /**
+     * 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.
+     */
+    rememberEvicted(viewPath, key, limit) {
+        let keys = this.evictedKeys.get(viewPath);
+        if (!keys) {
+            keys = new Set();
+            this.evictedKeys.set(viewPath, keys);
+        }
+        keys.delete(key);
+        keys.add(key);
+        while (keys.size > Math.max(limit, 1)) {
+            const oldest = keys.values().next().value;
+            if (oldest === undefined)
+                break;
+            keys.delete(oldest);
+        }
+    }
+    forgetEvicted(viewPath, key) {
+        this.evictedKeys.get(viewPath)?.delete(key);
+    }
+    reportDiscardedPatch(viewPath, frame) {
+        const seq = frame.seq ?? this.extractSeq(frame.data);
+        const evicted = this.evictedKeys.get(viewPath)?.has(frame.key) === true;
+        const error = evicted
+            ? new AreteError(`Discarded patch for '${frame.key}' in ${viewPath}: this client dropped the entity to `
+                + `stay within maxEntriesPerView (${String(this.maxEntriesPerView)}), and the server `
+                + 'sends no upsert for it until it re-enters the query or the subscription is '
+                + 're-established; raise maxEntriesPerView above the subscription size', 'PATCH_FOR_EVICTED_KEY')
+            : new AreteError(`Discarded patch for '${frame.key}' in ${viewPath}: the client holds no entity for `
+                + 'this key; it appears when the server sends a full upsert', 'PATCH_FOR_UNKNOWN_KEY');
+        const diagnostic = {
+            view: viewPath,
+            key: frame.key,
+            ...(seq !== undefined ? { seq } : {}),
+            operation: 'patch',
+            reason: evicted ? 'evicted-key' : 'unknown-key',
+            error,
+        };
+        this.reportDiagnostic(diagnostic);
+        if (evicted && this.warnOnValidationError && !this.warnedEvictedViews.has(viewPath)) {
+            this.warnedEvictedViews.add(viewPath);
+            console.warn('[Arete] Patch dropped for a locally evicted entity:', diagnostic);
         }
     }
 }
@@ -2627,6 +2795,66 @@ class MemoryAdapter {
     }
 }
 
+/** Whether a sort value cannot be ranked: it is missing or `null`. */
+function isUnrankedSortValue(value) {
+    return value === undefined || value === null;
+}
+/**
+ * Compares two ranked sort values in ascending order. Numbers and bigints
+ * compare numerically (also against each other), booleans as `false < true`,
+ * and everything else with `localeCompare` on its string form (the SDK
+ * ordering rule, shared with the Rust and Python SDKs).
+ *
+ * This is not the server's ranking. The server compares strings by byte
+ * order, except that two decimal-integer strings compare numerically, and it
+ * ranks numbers below strings and booleans below both. The server's order
+ * decides which entities fill a `take` window; this one only orders the
+ * members the client already holds, so the two can list a window's members
+ * differently, never choose different members.
+ */
+function compareSortValues(left, right) {
+    if (left === right)
+        return 0;
+    if (isUnrankedSortValue(left))
+        return isUnrankedSortValue(right) ? 0 : 1;
+    if (isUnrankedSortValue(right))
+        return -1;
+    if (typeof left === 'number' && typeof right === 'number')
+        return left - right;
+    if (typeof left === 'bigint' && typeof right === 'bigint')
+        return left < right ? -1 : 1;
+    if (typeof left === 'bigint' && typeof right === 'number' && Number.isInteger(right)) {
+        const other = BigInt(right);
+        return left === other ? 0 : left < other ? -1 : 1;
+    }
+    if (typeof left === 'number' && typeof right === 'bigint' && Number.isInteger(left)) {
+        const other = BigInt(left);
+        return other === right ? 0 : other < right ? -1 : 1;
+    }
+    if (typeof left === 'boolean' && typeof right === 'boolean')
+        return Number(left) - Number(right);
+    return String(left).localeCompare(String(right));
+}
+/**
+ * Orders two entities' sort values for a view sorted in `order`.
+ *
+ * A missing or `null` sort value cannot be ranked, so it sorts after every
+ * ranked value in both directions: `desc` reverses only the comparison between
+ * two ranked values. Two unranked values tie. Callers break ties on the entity
+ * key, ascending, whatever the order. The unranked-last rule is the server's
+ * and the Rust and Python SDKs'; how two ranked values compare is
+ * `compareRanked` (by default {@link compareSortValues}, which differs from
+ * the server as described there).
+ */
+function compareSortOrder(left, right, order, compareRanked = compareSortValues) {
+    const leftUnranked = isUnrankedSortValue(left);
+    const rightUnranked = isUnrankedSortValue(right);
+    if (leftUnranked || rightUnranked)
+        return Number(leftUnranked) - Number(rightUnranked);
+    const compared = compareRanked(left, right);
+    return order === 'desc' ? -compared : compared;
+}
+
 function getNestedValue$1(obj, path) {
     let current = obj;
     for (const segment of path) {
@@ -2638,33 +2866,6 @@ function getNestedValue$1(obj, path) {
     }
     return current;
 }
-function compareSortValues(a, b) {
-    if (a === b)
-        return 0;
-    if (a === undefined || a === null)
-        return -1;
-    if (b === undefined || b === null)
-        return 1;
-    if (typeof a === 'bigint' && typeof b === 'bigint') {
-        return a < b ? -1 : 1;
-    }
-    if (typeof a === 'number' && typeof b === 'number') {
-        return a - b;
-    }
-    if (typeof a === 'bigint' && typeof b === 'number' && Number.isInteger(b)) {
-        return a < BigInt(b) ? -1 : 1;
-    }
-    if (typeof a === 'number' && typeof b === 'bigint' && Number.isInteger(a)) {
-        return BigInt(a) < b ? -1 : 1;
-    }
-    if (typeof a === 'string' && typeof b === 'string') {
-        return a.localeCompare(b);
-    }
-    if (typeof a === 'boolean' && typeof b === 'boolean') {
-        return (a ? 1 : 0) - (b ? 1 : 0);
-    }
-    return String(a).localeCompare(String(b));
-}
 class SortedStorageDecorator {
     constructor(inner) {
         this.sortConfigs = new Map();
@@ -2784,7 +2985,6 @@ class SortedStorageDecorator {
     }
     binarySearchInsertPosition(viewPath, sortedKeys, sortConfig, newKey, newValue) {
         const newSortValue = getNestedValue$1(newValue, sortConfig.field);
-        const isDesc = sortConfig.order === 'desc';
         let low = 0;
         let high = sortedKeys.length;
         while (low < high) {
@@ -2792,9 +2992,8 @@ class SortedStorageDecorator {
             const midKey = sortedKeys[mid];
             const midEntity = this.inner.get(viewPath, midKey);
             const midValue = getNestedValue$1(midEntity, sortConfig.field);
-            let cmp = compareSortValues(newSortValue, midValue);
-            if (isDesc)
-                cmp = -cmp;
+            // Unranked (missing or null) values sort last in both directions.
+            let cmp = compareSortOrder(newSortValue, midValue, sortConfig.order);
             if (cmp === 0) {
                 cmp = newKey.localeCompare(midKey);
             }
@@ -2811,14 +3010,11 @@ class SortedStorageDecorator {
         const allKeys = this.inner.keys(viewPath);
         if (allKeys.length === 0)
             return;
-        const isDesc = sortConfig.order === 'desc';
         const entries = allKeys.map(k => [k, this.inner.get(viewPath, k)]);
         entries.sort((a, b) => {
             const aValue = getNestedValue$1(a[1], sortConfig.field);
             const bValue = getNestedValue$1(b[1], sortConfig.field);
-            let cmp = compareSortValues(aValue, bValue);
-            if (isDesc)
-                cmp = -cmp;
+            let cmp = compareSortOrder(aValue, bValue, sortConfig.order);
             if (cmp === 0) {
                 cmp = a[0].localeCompare(b[0]);
             }
@@ -2837,25 +3033,9 @@ function getNestedValue(value, path) {
     }
     return current;
 }
-function compareValues(left, right) {
-    if (left === right)
-        return 0;
-    if (left === undefined || left === null)
-        return -1;
-    if (right === undefined || right === null)
-        return 1;
-    if (typeof left === 'number' && typeof right === 'number')
-        return left - right;
-    if (typeof left === 'bigint' && typeof right === 'bigint')
-        return left < right ? -1 : 1;
-    if (typeof left === 'boolean' && typeof right === 'boolean') {
-        return Number(left) - Number(right);
-    }
-    return String(left).localeCompare(String(right));
-}
 function compareSequences(left, right) {
     if (typeof left !== 'string' || typeof right !== 'string')
-        return compareValues(left, right);
+        return compareSortValues(left, right);
     const [leftSlot, leftIndex = ''] = left.split(':', 2);
     const [rightSlot, rightIndex = ''] = right.split(':', 2);
     if (/^\d+$/.test(leftSlot ?? '') && /^\d+$/.test(rightSlot ?? '')) {
@@ -3147,9 +3327,9 @@ class QueryStore {
             const right = field
                 ? getNestedValue(this.storage.get(view, rightKey), field)
                 : record.sequences.get(rightKey);
-            let compared = field ? compareValues(left, right) : compareSequences(left, right);
-            if (order === 'desc')
-                compared = -compared;
+            // A missing or null sort value (or sequence) sorts after every ranked
+            // one in both directions; ties break on the key, always ascending.
+            const compared = compareSortOrder(left, right, order, field ? compareSortValues : compareSequences);
             return compared === 0 ? leftKey.localeCompare(rightKey) : compared;
         });
     }
@@ -3407,10 +3587,90 @@ function createRichUpdateStream(_storage, subscriptionRegistry, query, keyFilter
     };
 }
 
+/** How long `get` and `getOne` wait for an initial snapshot, as in the Rust and Python SDKs. */
+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.
+ */
+class InitialDataTimeoutError extends AreteError {
+    constructor(view, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for the initial snapshot of view '${view}'`, 'INITIAL_DATA_TIMEOUT', { view, timeoutMs });
+        this.view = view;
+        this.timeoutMs = timeoutMs;
+        this.name = 'InitialDataTimeoutError';
+    }
+}
 function queryOptions(options) {
-    const { schema: _schema, withSnapshot, ...query } = options ?? {};
+    const { schema: _schema, withSnapshot, timeoutMs: _timeoutMs, ...query } = options ?? {};
     return { query, snapshotEnabled: withSnapshot ?? true };
 }
+function resolveTimeout(options) {
+    const timeoutMs = options?.timeoutMs === undefined
+        ? DEFAULT_INITIAL_DATA_TIMEOUT_MS
+        : options.timeoutMs;
+    if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new RangeError('timeoutMs must be a positive finite number or null');
+    }
+    return timeoutMs;
+}
+/**
+ * Open (or reuse) the equivalent subscription, wait until its snapshot has
+ * resolved or its query has failed, and release it. A terminal connection
+ * failure or a disconnect rejects with that reason. Bounded by `timeoutMs`
+ * (`null` waits forever) so a socket that never delivers cannot hang the caller.
+ */
+async function readResolved(registry, query, snapshotEnabled, timeoutMs) {
+    const lease = registry.subscribe(query, snapshotEnabled);
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            let stop = () => { };
+            let timer;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                stop();
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const check = () => {
+                const error = lease.getError();
+                if (error)
+                    finish(error);
+                else if (!lease.getSnapshot().isLoading)
+                    finish();
+                else {
+                    const connectionError = registry.getConnectionError();
+                    if (connectionError)
+                        finish(connectionError);
+                }
+            };
+            check();
+            if (settled)
+                return;
+            const stopChanges = lease.onChange(check);
+            const stopFailures = registry.onFailure(finish);
+            stop = () => {
+                stopChanges();
+                stopFailures();
+            };
+            if (timeoutMs !== null) {
+                timer = setTimeout(() => finish(new InitialDataTimeoutError(query.view, timeoutMs)), timeoutMs);
+            }
+        });
+        return lease.getSnapshot();
+    }
+    finally {
+        lease.release();
+    }
+}
 function serializeViewKeyValue(value, view, field) {
     const location = field === undefined ? `view '${view}'` : `key field '${field}' for view '${view}'`;
     if (typeof value === 'string')
@@ -3461,7 +3721,10 @@ function createTypedStateView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, serializedKey, snapshotEnabled);
         },
         async get(key, options) {
-            return this.getSync(key, options) ?? null;
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, key: wireKey(key), ...query }, snapshotEnabled, timeoutMs);
+            return snapshot.data[0] ?? null;
         },
         getSync(key, options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -3489,7 +3752,14 @@ function createTypedListView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, undefined, snapshotEnabled);
         },
         async get(options) {
-            return this.getSync(options) ?? [];
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, ...query }, snapshotEnabled, timeoutMs);
+            return [...snapshot.data];
+        },
+        async getOne(options) {
+            const items = await this.get({ ...options, take: 1 });
+            return items[0] ?? null;
         },
         getSync(options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -6225,16 +6495,22 @@ const PROGRAM_READ_DESCRIPTOR = Symbol.for('@usearete/sdk/program-read-descripto
 /**
  * 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.
  */
 function withProgramRead(program, descriptor) {
     const properties = Object.getOwnPropertyDescriptors(program);
     Reflect.deleteProperty(properties, PROGRAM_READ_DESCRIPTOR);
+    Reflect.deleteProperty(properties, 'packageReleaseHash');
     const bundled = Object.create(Object.getPrototypeOf(program), properties);
     Object.defineProperty(bundled, PROGRAM_READ_DESCRIPTOR, {
         value: descriptor,
-        enumerable: false,
+        enumerable: true,
         configurable: false,
         writable: false,
     });
@@ -6244,9 +6520,62 @@ function withProgramRead(program, descriptor) {
 function getProgramReadDescriptor(program) {
     return program?.[PROGRAM_READ_DESCRIPTOR];
 }
+/**
+ * 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.
+ */
+function withProgramIdentity(program, identity) {
+    const properties = Object.getOwnPropertyDescriptors(program);
+    Reflect.deleteProperty(properties, 'packageReleaseHash');
+    const stamped = Object.create(Object.getPrototypeOf(program), properties);
+    if (typeof identity.packageReleaseHash === 'string' && identity.packageReleaseHash.length > 0) {
+        Object.defineProperty(stamped, 'packageReleaseHash', {
+            value: identity.packageReleaseHash,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return stamped;
+}
 
-const STACK_RUNTIME_EXTENSIONS = '__areteStackRuntimeExtensions';
-const PROGRAM_OPERATION_EXTENSIONS = '__areteProgramOperationExtensions';
+/**
+ * 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`.
+ */
+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.
+ */
+const STACK_RUNTIME_EXTENSIONS = Symbol.for('@usearete/sdk/stack-runtime-extensions');
+const PROGRAM_OPERATION_EXTENSIONS = Symbol.for('@usearete/sdk/program-runtime-extensions');
 function defineProgramExtensions() {
     return (extensions) => extensions;
 }
@@ -6275,7 +6604,12 @@ function extendProgram(program, extensions) {
     if (readDescriptor) {
         Object.defineProperty(extended, PROGRAM_READ_DESCRIPTOR, readDescriptor);
     }
+    // The extended program is no longer byte-for-byte the generated one, nor
+    // provably the program SDK its package release describes: extensions
+    // applied outside generated code must not borrow that identity. Generated
+    // entries stamp it back with `withProgramIdentity` after their own.
     delete extended.sdkDefinitionHash;
+    delete extended.packageReleaseHash;
     for (const key of ['pdas', 'accounts', 'queries', 'addresses', 'constants', 'defaults', 'math']) {
         const extensionValue = extensions[key];
         if (extensionValue !== undefined) {
@@ -6311,7 +6645,8 @@ function extendProgram(program, extensions) {
                     return mergeNamespace(baseRead, extensionReadFactory?.(context));
                 },
             },
-            enumerable: false,
+            // Enumerable so spreading the extended program keeps its operations.
+            enumerable: true,
             configurable: false,
             writable: false,
         });
@@ -6356,7 +6691,8 @@ function extendStack(stack, extensions) {
                     ? (client) => mergeNamespace(baseRuntime.createFlows(client), extensions.createFlows(client))
                     : extensions.createFlows ?? baseRuntime?.createFlows,
             },
-            enumerable: false,
+            // Enumerable so `{ ...stack }` keeps `read`, `flows` and `readArgCounts`.
+            enumerable: true,
             configurable: false,
             writable: false,
         });
@@ -6394,7 +6730,7 @@ function isPreparedInstruction(instruction) {
         && instruction.kind === 'instruction'
         && 'instruction' in instruction;
 }
-function nonEmpty(values, label) {
+function nonEmpty$1(values, label) {
     if (values.length === 0) {
         throw new Error(`${label} must contain at least one item`);
     }
@@ -6407,7 +6743,7 @@ function inferSignerAddresses(instructions) {
     return dedupe(instructions.flatMap((instruction) => instruction.keys.filter((key) => key.isSigner).map((key) => key.pubkey)));
 }
 function createPreparedTransactionBody(input) {
-    const instructions = nonEmpty(input.instructions, `Transaction '${input.name}'`);
+    const instructions = nonEmpty$1(input.instructions, `Transaction '${input.name}'`);
     return {
         name: input.name,
         instructions,
@@ -6420,7 +6756,7 @@ function createPlan(name, artifacts, transactions) {
     return {
         name,
         artifacts,
-        transactions: nonEmpty(transactions, `Flow '${name}'`),
+        transactions: nonEmpty$1(transactions, `Flow '${name}'`),
     };
 }
 function createPreparedInstruction(input) {
@@ -6706,8 +7042,8 @@ async function executePreparedOperation(host, operation, options = {}) {
             kind: 'flow',
             operationName: operation.name,
             artifacts: operation.artifacts,
-            signatures: nonEmpty(receipts.map((receipt) => receipt.signature), `Operation '${operation.name}' signatures`),
-            transactions: nonEmpty(receipts, `Operation '${operation.name}' receipts`),
+            signatures: nonEmpty$1(receipts.map((receipt) => receipt.signature), `Operation '${operation.name}' signatures`),
+            transactions: nonEmpty$1(receipts, `Operation '${operation.name}' receipts`),
             ...callbackErrorResult,
         };
     }
@@ -6983,6 +7319,127 @@ function createProgramReadTransport(config) {
     };
 }
 
+/** Error code for two different program SDKs claiming one program key. */
+const PROGRAM_KEY_CONFLICT = 'PROGRAM_KEY_CONFLICT';
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Compare two program definitions by identity, never by name. */
+function compareProgramIdentity(left, right) {
+    if (left === right)
+        return 'same';
+    const leftRelease = nonEmpty(left.packageReleaseHash);
+    const rightRelease = nonEmpty(right.packageReleaseHash);
+    if (leftRelease !== undefined && rightRelease !== undefined) {
+        return leftRelease === rightRelease ? 'same' : 'different';
+    }
+    const leftSpec = nonEmpty(left.programSpecHash);
+    return leftSpec !== undefined && leftSpec === nonEmpty(right.programSpecHash)
+        ? 'unproven'
+        : 'different';
+}
+/**
+ * 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.
+ */
+function isSameProgramSdk(left, right) {
+    return compareProgramIdentity(left, right) === 'same';
+}
+function identityOf(program) {
+    const release = nonEmpty(program.packageReleaseHash);
+    if (release !== undefined)
+        return `package release ${release}`;
+    const spec = nonEmpty(program.programSpecHash);
+    return spec !== undefined
+        ? `program spec ${spec}, no package release`
+        : 'no program identity';
+}
+const warned = new Set();
+/** Emit a program identity warning once per distinct message. */
+function warnOnce(message) {
+    if (warned.has(message))
+        return;
+    warned.add(message);
+    console.warn(`[Arete] ${message}`);
+}
+/**
+ * A program attached next to a stack (`withPrograms`, `ConnectOptions.programs`,
+ * `useArete(stack, { programs })`, a session member's `programs`) under a key
+ * the stack already provides with a different program SDK.
+ */
+function attachedProgramKeyConflict(stackName, key, stackProgram, attached) {
+    return new AreteError(`Program key '${key}' conflicts with stack '${stackName}': the stack already provides `
+        + `a different '${key}' program SDK (stack: ${identityOf(stackProgram)}; attached: `
+        + `${identityOf(attached)}). Use the stack's program at programs.${key}, or attach the `
+        + `other program under a different key, one the stack does not use.`, PROGRAM_KEY_CONFLICT, { key, stack: stackName });
+}
+/**
+ * An attached program replaces the stack's program under one key without a
+ * provable identity match (same program spec, no shared package release).
+ */
+function warnUnprovenAttachedProgram(stackName, key, stackProgram, attached) {
+    warnOnce(`programs.${key} uses the program attached to stack '${stackName}': it has the same `
+        + `program spec as the stack's '${key}' program but could not be proven identical `
+        + `(stack: ${identityOf(stackProgram)}; attached: ${identityOf(attached)}).`);
+}
+/** A standalone session program under a key a session stack already provides. */
+function sessionProgramKeyConflict(stackKey, key, stackProgram, standalone) {
+    return new AreteError(`Program key '${key}' conflicts with stack '${stackKey}' in this session: the stack `
+        + `already provides a different '${key}' program SDK (stack: ${identityOf(stackProgram)}; `
+        + `standalone: ${identityOf(standalone)}). Use session.stacks.${stackKey}.programs.${key}, `
+        + `or attach the standalone program under a different key in createSession({ programs }).`, PROGRAM_KEY_CONFLICT, { key, stack: stackKey });
+}
+/**
+ * A standalone session program takes the top-level key from stacks whose
+ * program it could not be proven identical to: a different identity
+ * (`'identity'`), or the same program SDK read through a different program
+ * read configuration than the stack's (`'program-read'`).
+ */
+function warnUnprovenSessionProgram(key, standalone, providers, cause = 'identity') {
+    const stacks = providers.map(({ stackKey }) => `'${stackKey}'`).join(' and ');
+    const paths = providers
+        .map(({ stackKey }) => `session.stacks.${stackKey}.programs.${key}`)
+        .join(' and ');
+    const identities = `standalone: ${identityOf(standalone)}; ${providers
+        .map(({ stackKey, program }) => `${stackKey}: ${identityOf(program)}`)
+        .join('; ')}`;
+    const reason = cause === 'program-read'
+        ? `it is the same program SDK as the '${key}' program of stack ${stacks} (${identities}) `
+            + `but its programReads.${key} descriptor differs from the one the stack reads through, `
+            + `so it keeps its own program read configuration`
+        : `it has the same program spec as the '${key}' program of stack ${stacks} but could not `
+            + `be proven identical (${identities})`;
+    warnOnce(`session.programs.${key} uses the standalone program: ${reason}. `
+        + `${paths} keep${providers.length === 1 ? 's' : ''} the stack's program.`);
+}
+/**
+ * Several session stacks bundle one key with the same program spec, not all
+ * provably the same SDK; the first stack's program takes the top-level key.
+ */
+function warnUnprovenStackPrograms(key, providers) {
+    const first = providers[0];
+    warnOnce(`session.programs.${key} uses stack '${first.stackKey}''s program: stacks `
+        + `${providers.map(({ stackKey }) => `'${stackKey}'`).join(' and ')} bundle '${key}' `
+        + `programs with the same program spec that could not be proven identical (${providers
+            .map(({ stackKey, program }) => `${stackKey}: ${identityOf(program)}`)
+            .join('; ')}). Each stays at session.stacks.<stack>.programs.${key}.`);
+}
+/** Two session stacks provide different program SDKs under one key. */
+function ambiguousSessionProgram(key, providers) {
+    const stacks = providers.map(({ stackKey }) => `'${stackKey}'`).join(' and ');
+    const paths = providers
+        .map(({ stackKey }) => `session.stacks.${stackKey}.programs.${key}`)
+        .join(' or ');
+    const identities = providers
+        .map(({ stackKey, program }) => `${stackKey}: ${identityOf(program)}`)
+        .join('; ');
+    return new AreteError(`session.programs.${key} is ambiguous: stacks ${stacks} provide different '${key}' `
+        + `program SDKs (${identities}). Use ${paths}, or attach the one you want under a `
+        + `different key in createSession({ programs }).`, PROGRAM_KEY_CONFLICT, { key, stacks: providers.map(({ stackKey }) => stackKey) });
+}
+
 function effectiveProgramRead(stack, name, override) {
     return override
         ?? stack.programReads?.[name]
@@ -7090,13 +7547,38 @@ function validateLocalProgramReadEndpoints(stack, overrides, connectHttpUrl) {
 function hasProgramAccountReads(definition) {
     return Object.keys(definition.accounts ?? {}).length > 0;
 }
+/**
+ * Attach programs next to a stack's own, matching a key the stack already
+ * provides by program identity (see `compareProgramIdentity`):
+ *
+ * - the same program SDK (same object, or equal `packageReleaseHash`) resolves
+ *   to the stack's definition;
+ * - the same `programSpecHash` without a provable identity match (at least one
+ *   side has no `packageReleaseHash`) uses the attached program, with one
+ *   warning;
+ * - anything else throws `PROGRAM_KEY_CONFLICT`.
+ */
 function mergeAttachedPrograms(stack, attachedPrograms) {
     const merged = { ...(attachedPrograms ?? {}) };
     for (const [name, definition] of Object.entries(stack.programs ?? {})) {
-        if (name in merged) {
-            console.warn(`Ignoring attached program '${name}' for stack '${stack.name}' because the stack already defines that key`);
+        const attached = attachedPrograms && Object.prototype.hasOwnProperty.call(attachedPrograms, name)
+            ? attachedPrograms[name]
+            : undefined;
+        if (attached === undefined) {
+            merged[name] = definition;
+            continue;
+        }
+        switch (compareProgramIdentity(definition, attached)) {
+            case 'same':
+                merged[name] = definition;
+                break;
+            case 'unproven':
+                warnUnprovenAttachedProgram(stack.name, name, definition, attached);
+                merged[name] = attached;
+                break;
+            case 'different':
+                throw attachedProgramKeyConflict(stack.name, name, definition, attached);
         }
-        merged[name] = definition;
     }
     return merged;
 }
@@ -7195,8 +7677,8 @@ let Arete$1 = class Arete {
         this.connection.onFrame((frame) => {
             this.processor.handleFrame(frame);
         });
-        this.connection.onStateChange((state) => {
-            this.subscriptionRegistry.handleConnectionState(state);
+        this.connection.onStateChange((state, error) => {
+            this.subscriptionRegistry.handleConnectionState(state, error);
         });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
         this._queries = this.buildQueries();
@@ -7696,6 +8178,34 @@ function resolveSessionProgramReads(stack, member, options) {
     }));
     return Object.keys(reads).length > 0 ? reads : undefined;
 }
+/**
+ * The program read descriptor a session member connected for `stack` reads
+ * `programKey` through, resolved the way `Arete.connect` resolves it: session
+ * and member overrides, then the stack's `programReads`, then the descriptor
+ * the program carries.
+ */
+function memberProgramRead(stack, programKey, member, options) {
+    return resolveSessionProgramReads(stack, member, options)?.[programKey]
+        ?? stack.programReads?.[programKey]
+        ?? getProgramReadDescriptor(stack.programs?.[programKey]);
+}
+/** Structural equality of two program read descriptors (plain JSON data). */
+function sameProgramRead(left, right) {
+    if (left === right)
+        return true;
+    if (left === null || right === null
+        || typeof left !== 'object' || typeof right !== 'object'
+        || Array.isArray(left) !== Array.isArray(right)) {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord).filter((key) => leftRecord[key] !== undefined);
+    const rightKeys = Object.keys(rightRecord).filter((key) => rightRecord[key] !== undefined);
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key) => Object.prototype.hasOwnProperty.call(rightRecord, key)
+            && sameProgramRead(leftRecord[key], rightRecord[key]));
+}
 function resolveMemberConnectOptions(stack, member, options, forceHttpOnly) {
     const transport = member?.transport ?? options?.transport ?? (forceHttpOnly ? 'http' : 'ws');
     // Stack endpoints remain on the stack definition. Only explicit session/member
@@ -7789,11 +8299,72 @@ async function createSession(definition, ...args) {
             validateCompositionProgramReads(programAsStack(key, program, definition.programReads?.[key]), options?.programs?.[key], options);
         }
     }
+    // Program identity, resolved before anything connects. Every stack's
+    // effective programs (its own plus member-attached ones, matched by
+    // `withPrograms`) are the providers for each key.
+    const effectiveStacks = new Map(stackEntries.map(([key, stack]) => {
+        const memberOptions = options?.stacks?.[key];
+        return [key, withPrograms(stack, memberOptions?.programs)];
+    }));
+    const stackProviders = new Map();
+    for (const [stackKey, stack] of effectiveStacks) {
+        for (const [programKey, program] of Object.entries(stack.programs ?? {})) {
+            const providers = stackProviders.get(programKey) ?? [];
+            providers.push({ stackKey, program });
+            stackProviders.set(programKey, providers);
+        }
+    }
+    // Standalone programs a stack already provides as the same program SDK, read
+    // through the same program read configuration, are served by that stack's
+    // connected instance instead of a second member. One with the same program
+    // spec but no provable identity match, or the same program SDK with its own
+    // `programReads` descriptor that differs from the stack's, gets its own
+    // member and takes session.programs.<key>; the stacks keep theirs.
+    const sharedStandalonePrograms = new Set();
+    if (definition.mode !== 'composition') {
+        for (const [programKey, program] of programEntries) {
+            const providers = stackProviders.get(programKey) ?? [];
+            if (providers.length === 0)
+                continue;
+            const matches = providers.map((provider) => ({
+                ...provider,
+                match: compareProgramIdentity(provider.program, program),
+            }));
+            const conflicting = matches.find(({ match }) => match === 'different');
+            if (conflicting) {
+                throw sessionProgramKeyConflict(conflicting.stackKey, programKey, conflicting.program, program);
+            }
+            if (matches.some(({ match }) => match === 'unproven')) {
+                warnUnprovenSessionProgram(programKey, program, providers);
+                continue;
+            }
+            const explicitRead = definition.programReads?.[programKey];
+            if (explicitRead !== undefined) {
+                // Sharing would read through the serving stack's configuration, so an
+                // explicit descriptor must resolve to the same one.
+                const servingStack = providers[0].stackKey;
+                const standaloneRead = memberProgramRead(programAsStack(programKey, program, explicitRead), programKey, options?.programs?.[programKey], options);
+                const stackRead = memberProgramRead(effectiveStacks.get(servingStack), programKey, options?.stacks?.[servingStack], options);
+                if (!sameProgramRead(standaloneRead, stackRead)) {
+                    warnUnprovenSessionProgram(programKey, program, providers, 'program-read');
+                    continue;
+                }
+            }
+            if (options?.programs?.[programKey] !== undefined) {
+                throw new AreteError(`Standalone program '${programKey}' is the same program SDK that stack `
+                    + `'${providers[0].stackKey}' provides, so the session serves it from the stack's `
+                    + `connected instance; configure it through options.stacks.${providers[0].stackKey} `
+                    + `instead of options.programs.${programKey}`, 'INVALID_CONFIG');
+            }
+            sharedStandalonePrograms.add(programKey);
+        }
+    }
+    const memberProgramEntries = programEntries.filter(([key]) => !sharedStandalonePrograms.has(key));
     let wallet = options?.wallet;
     const signerRegistry = options?.signerRegistry ?? createSignerRegistry();
     const connectedStacks = await Promise.all(stackEntries.map(async ([key, stack]) => {
         const memberOptions = options?.stacks?.[key];
-        const effectiveStack = withPrograms(stack, memberOptions?.programs);
+        const effectiveStack = effectiveStacks.get(key);
         const connectOptions = resolveMemberConnectOptions(effectiveStack, memberOptions, {
             ...options,
             chain: sharedChain,
@@ -7806,7 +8377,7 @@ async function createSession(definition, ...args) {
         });
         return [key, client];
     }));
-    const connectedPrograms = await Promise.all(programEntries.map(async ([key, program]) => {
+    const connectedPrograms = await Promise.all(memberProgramEntries.map(async ([key, program]) => {
         const syntheticStack = programAsStack(key, program, definition.programReads?.[key]);
         const connectOptions = resolveMemberConnectOptions(syntheticStack, options?.programs?.[key], {
             ...options,
@@ -7823,30 +8394,38 @@ async function createSession(definition, ...args) {
     const executionHost = memberClients[0];
     const transactions = sharedTransactions ?? executionHost.transactions;
     const stacks = Object.fromEntries(connectedStacks);
-    const explicitProgramKeys = new Set(connectedPrograms.map(([key]) => key));
-    const programOwners = new Map();
     const connectedProgramEntries = connectedPrograms.map(([key, client]) => [
         key,
         client.programs[key],
     ]);
     const promotedPrograms = Object.fromEntries(connectedProgramEntries);
     if (definition.mode !== 'composition') {
-        for (const [stackKey, client] of connectedStacks) {
-            for (const [programKey, program] of Object.entries(client.programs)) {
-                if (explicitProgramKeys.has(programKey)) {
-                    continue;
-                }
-                const existingOwner = programOwners.get(programKey);
-                if (existingOwner) {
-                    console.warn(`Program '${programKey}' is bundled by stacks '${existingOwner.stack}'` +
-                        ` (${existingOwner.programId ?? 'unknown program ID'}) and '${stackKey}'` +
-                        ` (${program.programId ?? 'unknown program ID'}); session.programs.${programKey}` +
-                        ` uses '${existingOwner.stack}' because it was connected first`);
-                    continue;
-                }
-                promotedPrograms[programKey] = program;
-                programOwners.set(programKey, { stack: stackKey, programId: program.programId });
+        const connectedStackClients = new Map(connectedStacks);
+        for (const [programKey, providers] of stackProviders) {
+            if (Object.prototype.hasOwnProperty.call(promotedPrograms, programKey))
+                continue;
+            const first = providers[0];
+            const matches = providers.flatMap((left, index) => providers.slice(index + 1).map((right) => compareProgramIdentity(left.program, right.program)));
+            if (!matches.includes('different')) {
+                // One program, however many stacks bundle it: the first stack's
+                // connected instance serves the top-level key. Copies with the same
+                // program spec that cannot be proven identical say so once.
+                if (matches.includes('unproven'))
+                    warnUnprovenStackPrograms(programKey, providers);
+                promotedPrograms[programKey] = connectedStackClients.get(first.stackKey).programs[programKey];
+                continue;
             }
+            // Different program SDKs under one key: every stack keeps its own at
+            // session.stacks.<stack>.programs.<key>, and the ambiguous top-level key
+            // explains how to choose instead of silently picking one.
+            const error = ambiguousSessionProgram(programKey, providers);
+            Object.defineProperty(promotedPrograms, programKey, {
+                get() {
+                    throw error;
+                },
+                enumerable: false,
+                configurable: true,
+            });
         }
     }
     const programs = promotedPrograms;
@@ -8082,5 +8661,5 @@ function stringifyBigints(value) {
 
 const Arete = Object.assign(Arete$1, { session: createSession });
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, 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 { 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 };
 //# sourceMappingURL=index.esm.js.map