@usearete/sdk 0.24.0 → 0.25.0

package/dist/index.cjs

@@ -1874,6 +1874,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}`);
@@ -1934,6 +1935,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)
@@ -1944,6 +1948,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.
@@ -1962,6 +1976,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
@@ -2009,18 +2032,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;
@@ -2087,6 +2114,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;
@@ -2307,6 +2378,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, {
@@ -2331,10 +2403,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,
@@ -2353,18 +2426,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,
@@ -2381,14 +2460,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,
@@ -2405,6 +2487,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',
@@ -2413,7 +2508,7 @@ class FrameProcessor {
                 if (normalizedPatch === null) {
                     break;
                 }
-                if (duplicateOrStaleSequence && existing !== null) {
+                if (duplicateOrStale && existing !== null) {
                     const update = {
                         type: 'patch',
                         key: frame.key,
@@ -2426,7 +2521,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',
@@ -2445,6 +2540,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,
@@ -2481,8 +2577,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);
         }
     }
 }
@@ -2629,6 +2773,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) {
@@ -2640,33 +2844,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();
@@ -2786,7 +2963,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) {
@@ -2794,9 +2970,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);
             }
@@ -2813,14 +2988,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]);
             }
@@ -2839,25 +3011,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 ?? '')) {
@@ -3149,9 +3305,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;
         });
     }
@@ -6227,16 +6383,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,
     });
@@ -6246,9 +6408,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;
 }
@@ -6277,7 +6492,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) {
@@ -6313,7 +6533,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,
         });
@@ -6358,7 +6579,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,
         });
@@ -6396,7 +6618,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`);
     }
@@ -6409,7 +6631,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,
@@ -6422,7 +6644,7 @@ function createPlan(name, artifacts, transactions) {
     return {
         name,
         artifacts,
-        transactions: nonEmpty(transactions, `Flow '${name}'`),
+        transactions: nonEmpty$1(transactions, `Flow '${name}'`),
     };
 }
 function createPreparedInstruction(input) {
@@ -6708,8 +6930,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,
         };
     }
@@ -6985,6 +7207,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]
@@ -7092,13 +7435,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;
 }
@@ -7698,6 +8066,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
@@ -7791,11 +8187,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,
@@ -7808,7 +8265,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,
@@ -7825,30 +8282,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;
@@ -8090,12 +8555,14 @@ exports.AreteError = AreteError;
 exports.ConnectionManager = ConnectionManager;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.DEFAULT_MAX_ENTRIES_PER_VIEW = DEFAULT_MAX_ENTRIES_PER_VIEW;
+exports.EXTENSION_API_VERSION = EXTENSION_API_VERSION;
 exports.FrameProcessor = FrameProcessor;
 exports.InstructionError = InstructionError;
 exports.MemoryAdapter = MemoryAdapter;
 exports.OPERATION_KIND = OPERATION_KIND;
 exports.OperationCallbackError = OperationCallbackError;
 exports.OperationExecutionError = OperationExecutionError;
+exports.PROGRAM_KEY_CONFLICT = PROGRAM_KEY_CONFLICT;
 exports.PROGRAM_OPERATION_EXTENSIONS = PROGRAM_OPERATION_EXTENSIONS;
 exports.ProcessedSlotTimeoutError = ProcessedSlotTimeoutError;
 exports.QueryStore = QueryStore;
@@ -8119,6 +8586,7 @@ exports.buildInstruction = buildInstruction;
 exports.bytes = bytes;
 exports.canonicalQueryKey = canonicalQueryKey;
 exports.chainAccountLoader = chainAccountLoader;
+exports.compareProgramIdentity = compareProgramIdentity;
 exports.createChainClient = createChainClient;
 exports.createEntityStream = createEntityStream;
 exports.createHostedSolanaGatewayTransports = createHostedSolanaGatewayTransports;
@@ -8171,6 +8639,7 @@ exports.isEntityFrame = isEntityFrame;
 exports.isErrorFrame = isErrorFrame;
 exports.isHostedAreteEndpoint = isHostedAreteEndpoint;
 exports.isReplayErrorCode = isReplayErrorCode;
+exports.isSameProgramSdk = isSameProgramSdk;
 exports.isSnapshotFrame = isSnapshotFrame;
 exports.isStackVersionRefusalCode = isStackVersionRefusalCode;
 exports.isSubscribedFrame = isSubscribedFrame;
@@ -8210,6 +8679,7 @@ exports.unwrapOperationExecutionError = unwrapOperationExecutionError;
 exports.validateAccountResolution = validateAccountResolution;
 exports.validateProgramReadDescriptor = validateProgramReadDescriptor;
 exports.validateSubscriptionId = validateSubscriptionId;
+exports.withProgramIdentity = withProgramIdentity;
 exports.withProgramRead = withProgramRead;
 exports.withPrograms = withPrograms;
 //# sourceMappingURL=index.cjs.map