@oimdb/core 3.7.0 → 3.9.0

package/dist/index.js

@@ -227,21 +227,82 @@ var OIMEventQueueScheduler = class {
   }
 };
 
+// src/core/OIMKeyedBucketSetBased.ts
+var OIMKeyedBucketSetBased = class extends Set {
+  constructor(key) {
+    super();
+    this.key = key;
+  }
+  hasSubscribers() {
+    return this.subscribers !== void 0 && this.subscribers.size > 0;
+  }
+  /** Clearing the slot set also clears the pk membership — they stay in sync. */
+  clear() {
+    super.clear();
+    this.membership?.clear();
+  }
+};
+
 // src/core/OIMIndexStoreMapDrivenSetBased.ts
 var OIMIndexStoreMapDrivenSetBased = class extends OIMIndexStoreSetBased {
   constructor() {
     super(...arguments);
+    // Live buckets (non-empty, or freshly promoted). Enumeration reads these only.
     this.slots = /* @__PURE__ */ new Map();
+    // Empty buckets kept alive solely by their subscribers, so a subscription
+    // survives a key going empty → re-filled. Invisible to reads/enumeration.
+    this.reservedBuckets = /* @__PURE__ */ new Map();
+  }
+  getOrReserveBucket(key) {
+    const live = this.slots.get(key);
+    if (live) return live;
+    let reserved = this.reservedBuckets.get(key);
+    if (!reserved) {
+      reserved = new OIMKeyedBucketSetBased(key);
+      this.reservedBuckets.set(key, reserved);
+    }
+    return reserved;
+  }
+  findBucket(key) {
+    return this.slots.get(key) ?? this.reservedBuckets.get(key);
+  }
+  retainBucket(bucket) {
+    if (bucket.size === 0) return;
+    this.reservedBuckets.delete(bucket.key);
+    if (!this.slots.has(bucket.key)) this.slots.set(bucket.key, bucket);
+  }
+  releaseBucket(bucket) {
+    if (bucket.size > 0) return;
+    this.slots.delete(bucket.key);
+    if (bucket.hasSubscribers()) {
+      this.reservedBuckets.set(bucket.key, bucket);
+    } else {
+      this.reservedBuckets.delete(bucket.key);
+    }
+  }
+  dropIfReserved(key) {
+    const reserved = this.reservedBuckets.get(key);
+    if (reserved && reserved.size === 0 && !reserved.hasSubscribers()) {
+      this.reservedBuckets.delete(key);
+    }
   }
   setOneByKey(key, slots) {
-    this.slots.set(key, slots);
+    const bucket = this.getOrReserveBucket(key);
+    if (bucket !== slots) {
+      bucket.clear();
+      for (const slot of slots) bucket.add(slot);
+    }
+    if (bucket.size > 0) this.retainBucket(bucket);
+    else this.releaseBucket(bucket);
   }
   removeOneByKey(key) {
     this.slots.delete(key);
+    this.reservedBuckets.delete(key);
   }
   removeManyByKeys(keys) {
     for (const key of keys) {
       this.slots.delete(key);
+      this.reservedBuckets.delete(key);
     }
   }
   getOneByKey(key) {
@@ -250,10 +311,8 @@ var OIMIndexStoreMapDrivenSetBased = class extends OIMIndexStoreSetBased {
   getManyByKeys(keys) {
     const result = /* @__PURE__ */ new Map();
     for (const key of keys) {
-      const slots = this.getOneByKey(key);
-      if (slots !== void 0) {
-        result.set(key, slots);
-      }
+      const slots = this.slots.get(key);
+      if (slots !== void 0) result.set(key, slots);
     }
     return result;
   }
@@ -267,6 +326,12 @@ var OIMIndexStoreMapDrivenSetBased = class extends OIMIndexStoreSetBased {
     return this.slots.size;
   }
   clear() {
+    for (const bucket of this.slots.values()) {
+      bucket.clear();
+      if (bucket.hasSubscribers()) {
+        this.reservedBuckets.set(bucket.key, bucket);
+      }
+    }
     this.slots.clear();
   }
 };
@@ -274,10 +339,9 @@ var OIMIndexStoreMapDrivenSetBased = class extends OIMIndexStoreSetBased {
 // src/abstract/OIMIndexSetBased.ts
 var OIMIndexSetBased = class extends OIMIndex {
   constructor(options = {}) {
-    super(
-      options.store ?? new OIMIndexStoreMapDrivenSetBased(),
-      options.comparePks
-    );
+    const store = options.store ?? new OIMIndexStoreMapDrivenSetBased();
+    super(store, options.comparePks);
+    this.setStore = store;
   }
   getBucketSize(bucket) {
     return bucket.size;
@@ -305,22 +369,36 @@ var OIMIndexSetBased = class extends OIMIndex {
     for (const slot of slots) pks.add(slot.pk);
     return pks;
   }
-  setSlotsWithComparison(key, newSlots) {
-    if (this.comparePks) {
-      const existingSlotsSet = this.store.getOneByKey(key);
-      if (existingSlotsSet && existingSlotsSet.size === newSlots.size) {
-        if (this.comparePks(
-          Array.from(this.slotsToPks(existingSlotsSet)),
-          Array.from(this.slotsToPks(newSlots))
-        )) {
-          return false;
-        }
-      } else if (!existingSlotsSet && newSlots.size === 0) {
-        return false;
-      }
-    }
-    this.store.setOneByKey(key, newSlots);
-    return true;
+  /**
+   * True if a comparator is set and considers `bucket`'s current pks equal to
+   * `newSlots` — i.e. a `setSlots` would be a no-op and should not emit.
+   */
+  bucketMatchesComparator(bucket, newSlots) {
+    if (!this.comparePks) return false;
+    if (bucket.size !== newSlots.size) return false;
+    if (bucket.size === 0) return true;
+    return this.comparePks(
+      Array.from(this.slotsToPks(bucket)),
+      Array.from(this.slotsToPks(newSlots))
+    );
+  }
+};
+
+// src/core/OIMKeyedBucketArrayBased.ts
+var OIMKeyedBucketArrayBased = class extends Array {
+  constructor(key) {
+    super();
+    this.key = key;
+  }
+  static get [Symbol.species]() {
+    return Array;
+  }
+  hasSubscribers() {
+    return this.subscribers !== void 0 && this.subscribers.size > 0;
+  }
+  /** Empty the bucket in place (Array has no `clear`). */
+  clear() {
+    this.length = 0;
   }
 };
 
@@ -328,17 +406,61 @@ var OIMIndexSetBased = class extends OIMIndex {
 var OIMIndexStoreMapDrivenArrayBased = class extends OIMIndexStoreArrayBased {
   constructor() {
     super(...arguments);
+    // Live buckets (non-empty). Enumeration reads these only.
     this.slots = /* @__PURE__ */ new Map();
+    // Empty buckets kept alive by their subscribers, invisible to reads.
+    this.reservedBuckets = /* @__PURE__ */ new Map();
+  }
+  getOrReserveBucket(key) {
+    const live = this.slots.get(key);
+    if (live) return live;
+    let reserved = this.reservedBuckets.get(key);
+    if (!reserved) {
+      reserved = new OIMKeyedBucketArrayBased(key);
+      this.reservedBuckets.set(key, reserved);
+    }
+    return reserved;
+  }
+  findBucket(key) {
+    return this.slots.get(key) ?? this.reservedBuckets.get(key);
+  }
+  retainBucket(bucket) {
+    if (bucket.length === 0) return;
+    this.reservedBuckets.delete(bucket.key);
+    if (!this.slots.has(bucket.key)) this.slots.set(bucket.key, bucket);
+  }
+  releaseBucket(bucket) {
+    if (bucket.length > 0) return;
+    this.slots.delete(bucket.key);
+    if (bucket.hasSubscribers()) {
+      this.reservedBuckets.set(bucket.key, bucket);
+    } else {
+      this.reservedBuckets.delete(bucket.key);
+    }
+  }
+  dropIfReserved(key) {
+    const reserved = this.reservedBuckets.get(key);
+    if (reserved && reserved.length === 0 && !reserved.hasSubscribers()) {
+      this.reservedBuckets.delete(key);
+    }
   }
   setOneByKey(key, slots) {
-    this.slots.set(key, slots);
+    const bucket = this.getOrReserveBucket(key);
+    if (bucket !== slots) {
+      bucket.length = 0;
+      for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
+    }
+    if (bucket.length > 0) this.retainBucket(bucket);
+    else this.releaseBucket(bucket);
   }
   removeOneByKey(key) {
     this.slots.delete(key);
+    this.reservedBuckets.delete(key);
   }
   removeManyByKeys(keys) {
     for (const key of keys) {
       this.slots.delete(key);
+      this.reservedBuckets.delete(key);
     }
   }
   getOneByKey(key) {
@@ -347,10 +469,8 @@ var OIMIndexStoreMapDrivenArrayBased = class extends OIMIndexStoreArrayBased {
   getManyByKeys(keys) {
     const result = /* @__PURE__ */ new Map();
     for (const key of keys) {
-      const slots = this.getOneByKey(key);
-      if (slots !== void 0) {
-        result.set(key, slots);
-      }
+      const slots = this.slots.get(key);
+      if (slots !== void 0) result.set(key, slots);
     }
     return result;
   }
@@ -364,6 +484,12 @@ var OIMIndexStoreMapDrivenArrayBased = class extends OIMIndexStoreArrayBased {
     return this.slots.size;
   }
   clear() {
+    for (const bucket of this.slots.values()) {
+      bucket.length = 0;
+      if (bucket.hasSubscribers()) {
+        this.reservedBuckets.set(bucket.key, bucket);
+      }
+    }
     this.slots.clear();
   }
 };
@@ -371,10 +497,9 @@ var OIMIndexStoreMapDrivenArrayBased = class extends OIMIndexStoreArrayBased {
 // src/abstract/OIMIndexArrayBased.ts
 var OIMIndexArrayBased = class extends OIMIndex {
   constructor(options = {}) {
-    super(
-      options.store ?? new OIMIndexStoreMapDrivenArrayBased(),
-      options.comparePks
-    );
+    const store = options.store ?? new OIMIndexStoreMapDrivenArrayBased();
+    super(store, options.comparePks);
+    this.arrayStore = store;
   }
   getBucketSize(bucket) {
     return bucket.length;
@@ -392,10 +517,15 @@ var OIMIndexArrayBased = class extends OIMIndex {
     return result;
   }
   getSlotsByKey(key) {
-    return this.store.getOneByKey(key) ?? [];
+    const bucket = this.store.getOneByKey(key);
+    return bucket ? bucket.slice() : [];
   }
   getSlotsByKeys(keys) {
-    return this.store.getManyByKeys(keys);
+    const result = /* @__PURE__ */ new Map();
+    for (const [key, bucket] of this.store.getManyByKeys(keys)) {
+      result.set(key, bucket.slice());
+    }
+    return result;
   }
   slotsToPks(slots) {
     const pks = [];
@@ -403,28 +533,24 @@ var OIMIndexArrayBased = class extends OIMIndex {
     for (let i = 0; i < slots.length; i++) pks[i] = slots[i].pk;
     return pks;
   }
-  setSlotsWithComparison(key, newSlots) {
-    if (this.comparePks) {
-      const existingSlotsArray = this.store.getOneByKey(key);
-      if (existingSlotsArray && existingSlotsArray.length === newSlots.length) {
-        if (this.comparePks(
-          this.slotsToPks(existingSlotsArray),
-          this.slotsToPks(newSlots)
-        )) {
-          return false;
-        }
-      } else if (!existingSlotsArray && newSlots.length === 0) {
-        return false;
-      }
-    }
-    this.store.setOneByKey(key, newSlots);
-    return true;
+  /**
+   * True if a comparator is set and considers `bucket`'s pks equal to
+   * `newSlots` — i.e. a `setSlots` would be a no-op and should not emit.
+   */
+  bucketMatchesComparator(bucket, newSlots) {
+    if (!this.comparePks) return false;
+    if (bucket.length !== newSlots.length) return false;
+    if (bucket.length === 0) return true;
+    return this.comparePks(
+      this.slotsToPks(bucket),
+      this.slotsToPks(newSlots)
+    );
   }
 };
 
 // src/core/OIMCarrierKeyedEmitter.ts
 var OIMCarrierKeyedEmitter = class {
-  constructor(queue, resolver) {
+  constructor(queue, carrierProvider) {
     // Carriers with at least one subscriber — for markAllUpdated / metrics.
     this.subscribedCarriers = /* @__PURE__ */ new Set();
     // Pending flush batch. A plain array + a `carrier.dirty` flag for dedup —
@@ -449,17 +575,17 @@ var OIMCarrierKeyedEmitter = class {
       }
     };
     this.queue = queue;
-    this.resolver = resolver;
+    this.carrierProvider = carrierProvider;
   }
   subscribeOnKey(key, handler) {
-    const carrier = this.resolver.getOrReserveCarrier(key);
+    const carrier = this.carrierProvider.getOrReserveCarrier(key);
     this.addHandler(carrier, handler);
     return () => this.removeHandler(carrier, handler);
   }
   subscribeOnKeys(keys, handler) {
     const carriers = [];
     for (let i = 0; i < keys.length; i++) {
-      const carrier = this.resolver.getOrReserveCarrier(keys[i]);
+      const carrier = this.carrierProvider.getOrReserveCarrier(keys[i]);
       this.addHandler(carrier, handler);
       carriers.push(carrier);
     }
@@ -470,7 +596,7 @@ var OIMCarrierKeyedEmitter = class {
     };
   }
   unsubscribeFromKey(key, handler) {
-    const carrier = this.resolver.findCarrier(key);
+    const carrier = this.carrierProvider.findCarrier(key);
     if (carrier) this.removeHandler(carrier, handler);
   }
   unsubscribeFromKeys(keys, handler) {
@@ -493,7 +619,7 @@ var OIMCarrierKeyedEmitter = class {
     subscribers.delete(handler);
     if (subscribers.size === 0) {
       this.subscribedCarriers.delete(carrier);
-      this.resolver.onCarrierEmptied?.(carrier);
+      this.carrierProvider.onCarrierEmptied?.(carrier);
     }
   }
   /** Fast path: the writer already holds the carrier. */
@@ -507,11 +633,19 @@ var OIMCarrierKeyedEmitter = class {
     this.scheduleFlush();
   }
   markUpdatedKey(key) {
-    const carrier = this.resolver.findCarrier(key);
+    if (this.subscribedCarriers.size === 0) {
+      this.assertNotInFlush();
+      return;
+    }
+    const carrier = this.carrierProvider.findCarrier(key);
     if (carrier) this.markUpdatedCarrier(carrier);
     else this.assertNotInFlush();
   }
   markUpdatedKeys(keys) {
+    if (this.subscribedCarriers.size === 0) {
+      this.assertNotInFlush();
+      return;
+    }
     for (let i = 0; i < keys.length; i++) this.markUpdatedKey(keys[i]);
   }
   markAllUpdated() {
@@ -528,7 +662,7 @@ var OIMCarrierKeyedEmitter = class {
     return this.subscribedCarriers.size > 0;
   }
   getHandlerCount(key) {
-    return this.resolver.findCarrier(key)?.subscribers?.size ?? 0;
+    return this.carrierProvider.findCarrier(key)?.subscribers?.size ?? 0;
   }
   getMetrics() {
     let totalHandlers = 0;
@@ -588,8 +722,8 @@ var OIMCarrierKeyedEmitter = class {
   }
 };
 
-// src/core/OIMKeyedCarrierResolver.ts
-var OIMKeyedCarrierResolver = class {
+// src/core/OIMKeyedCarrierProvider.ts
+var OIMKeyedCarrierProvider = class {
   constructor() {
     this.carriers = /* @__PURE__ */ new Map();
   }
@@ -611,8 +745,8 @@ var OIMKeyedCarrierResolver = class {
 
 // src/abstract/OIMReactiveIndex.ts
 var OIMReactiveIndex = class {
-  constructor(queue, createIndex) {
-    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierResolver());
+  constructor(queue, createIndex, createCarrierProvider = () => new OIMKeyedCarrierProvider()) {
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, createCarrierProvider());
     this.index = createIndex(this.updateEmitter);
   }
   getEntitiesByKey(key) {
@@ -668,8 +802,8 @@ var OIMReactiveIndex = class {
 
 // src/abstract/OIMReactiveIndexSetBased.ts
 var OIMReactiveIndexSetBased = class extends OIMReactiveIndex {
-  constructor(queue, createIndex) {
-    super(queue, createIndex);
+  constructor(queue, createIndex, createCarrierProvider) {
+    super(queue, createIndex, createCarrierProvider);
   }
   getPksByKey(key) {
     return this.index.getPksByKey(key);
@@ -687,8 +821,8 @@ var OIMReactiveIndexSetBased = class extends OIMReactiveIndex {
 
 // src/abstract/OIMReactiveIndexArrayBased.ts
 var OIMReactiveIndexArrayBased = class extends OIMReactiveIndex {
-  constructor(queue, createIndex) {
-    super(queue, createIndex);
+  constructor(queue, createIndex, createCarrierProvider) {
+    super(queue, createIndex, createCarrierProvider);
   }
   getPksByKey(key) {
     return this.index.getPksByKey(key);
@@ -1151,6 +1285,14 @@ var OIMCollection = class {
   getOrReserveSlotByPk(pk) {
     return this.store.getOrReserveSlotByPk(pk);
   }
+  /**
+   * The existing slot for `pk` (live or reserved) WITHOUT creating one — used
+   * by indexes to resolve a pk to its canonical slot for removal (delete by
+   * reference), with no side effect for a pk that is not present.
+   */
+  findSlotByPk(pk) {
+    return this.store.findSlotByPk(pk);
+  }
   getSlotsByPks(pks) {
     return this.store.getSlotsByPks(pks);
   }
@@ -1219,15 +1361,12 @@ var OIMCollection = class {
         `[OIMCollection]: PK is required to upsert an entity ${JSON.stringify(entity)}`
       );
     }
-    const existingEntity = this.store.getOneByPk(pk);
-    if (existingEntity) {
-      return this.store.setOneByPk(
-        pk,
-        this.updateEntity(entity, existingEntity)
-      );
-    } else {
-      return this.store.setOneByPk(pk, entity);
+    const slot = this.store.getSlotByPk(pk);
+    if (slot !== void 0 && slot.item !== void 0) {
+      slot.item = this.updateEntity(entity, slot.item);
+      return slot;
     }
+    return this.store.setOneByPk(pk, entity);
   }
   destroy() {
     this.store.destroy();
@@ -1240,13 +1379,15 @@ var OIMReactiveCollection = class extends OIMCollection {
   constructor(queue, opts) {
     super(opts);
     this.anyUpdateHandlers = /* @__PURE__ */ new Set();
+    // Only ever holds `slot.pk` (one canonical reference per logical key), so a
+    // native `Set` dedups correctly by reference even for composite pks.
     this.pendingAnyUpdatePks = /* @__PURE__ */ new Set();
     this.isAnyUpdateClearPending = false;
     this.isAnyUpdateScheduled = false;
     this.runAnyUpdate = () => {
       if (!this.isAnyUpdateScheduled) return;
       this.isAnyUpdateScheduled = false;
-      const pks = this.isAnyUpdateClearPending ? [] : Array.from(this.pendingAnyUpdatePks);
+      const pks = this.isAnyUpdateClearPending ? [] : Array.from(this.pendingAnyUpdatePks.values());
       this.pendingAnyUpdatePks.clear();
       this.isAnyUpdateClearPending = false;
       const snapshot = Array.from(this.anyUpdateHandlers);
@@ -1405,38 +1546,40 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
     if (key === void 0) {
       const keys = this.getKeys();
       if (keys.length > 0) {
-        this.store.clear();
+        this.arrayStore.clear();
         this.emitUpdate(Array.from(keys));
       }
       return;
     }
-    if (this.store.getOneByKey(key) !== void 0) {
-      this.store.removeOneByKey(key);
+    const bucket = this.arrayStore.findBucket(key);
+    if (bucket && bucket.length > 0) {
+      bucket.length = 0;
+      this.arrayStore.releaseBucket(bucket);
       this.emitUpdate([key]);
     }
   }
   pushSlot(key, slot) {
-    const list = this.getOrCreateList(key);
-    const index = list.length;
-    list.push(slot);
+    const bucket = this.arrayStore.getOrReserveBucket(key);
+    const index = bucket.length;
+    bucket.push(slot);
+    this.arrayStore.retainBucket(bucket);
     this.emitUpdate([key]);
     return index;
   }
   insertSlotAt(key, index, slot) {
-    const list = this.getOrCreateList(key);
-    const safeIndex = Math.max(0, Math.min(index, list.length));
-    list.splice(safeIndex, 0, slot);
+    const bucket = this.arrayStore.getOrReserveBucket(key);
+    const safeIndex = Math.max(0, Math.min(index, bucket.length));
+    bucket.splice(safeIndex, 0, slot);
+    this.arrayStore.retainBucket(bucket);
     this.emitUpdate([key]);
     return safeIndex;
   }
   removeAt(key, index) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return void 0;
-    if (index < 0 || index >= list.length) return void 0;
-    const [removed] = list.splice(index, 1);
-    if (list.length === 0) {
-      this.store.removeOneByKey(key);
-    }
+    const bucket = this.arrayStore.findBucket(key);
+    if (!bucket) return void 0;
+    if (index < 0 || index >= bucket.length) return void 0;
+    const [removed] = bucket.splice(index, 1);
+    if (bucket.length === 0) this.arrayStore.releaseBucket(bucket);
     this.emitUpdate([key]);
     return removed;
   }
@@ -1445,35 +1588,33 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
    * Returns the number actually removed (clamped to bounds; 0 if nothing).
    */
   removeRange(key, index, count) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return 0;
-    if (index < 0 || index >= list.length || count <= 0) return 0;
-    const actual = Math.min(count, list.length - index);
-    list.splice(index, actual);
-    if (list.length === 0) {
-      this.store.removeOneByKey(key);
-    }
+    const bucket = this.arrayStore.findBucket(key);
+    if (!bucket) return 0;
+    if (index < 0 || index >= bucket.length || count <= 0) return 0;
+    const actual = Math.min(count, bucket.length - index);
+    bucket.splice(index, actual);
+    if (bucket.length === 0) this.arrayStore.releaseBucket(bucket);
     this.emitUpdate([key]);
     return actual;
   }
   move(key, fromIndex, toIndex) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return void 0;
-    if (fromIndex < 0 || fromIndex >= list.length) return void 0;
-    if (toIndex < 0 || toIndex >= list.length) return void 0;
-    if (fromIndex === toIndex) return list[fromIndex];
-    const [slot] = list.splice(fromIndex, 1);
+    const bucket = this.arrayStore.findBucket(key);
+    if (!bucket) return void 0;
+    if (fromIndex < 0 || fromIndex >= bucket.length) return void 0;
+    if (toIndex < 0 || toIndex >= bucket.length) return void 0;
+    if (fromIndex === toIndex) return bucket[fromIndex];
+    const [slot] = bucket.splice(fromIndex, 1);
     if (slot === void 0) return void 0;
-    list.splice(toIndex, 0, slot);
+    bucket.splice(toIndex, 0, slot);
     this.emitUpdate([key]);
     return slot;
   }
   /** Replace the slot at `index` in place. Returns the safe index, or -1. */
   setSlotAt(key, index, slot) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return -1;
-    if (index < 0 || index >= list.length) return -1;
-    list[index] = slot;
+    const bucket = this.arrayStore.findBucket(key);
+    if (!bucket) return -1;
+    if (index < 0 || index >= bucket.length) return -1;
+    bucket[index] = slot;
     this.emitUpdate([key]);
     return index;
   }
@@ -1483,52 +1624,49 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
    * Returns the number actually moved (0 if a no-op / out of bounds).
    */
   moveRange(key, from, to, count) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return 0;
-    if (from < 0 || from >= list.length || count <= 0) return 0;
-    const actual = Math.min(count, list.length - from);
-    const insertAt = Math.max(0, Math.min(to, list.length - actual));
+    const bucket = this.arrayStore.findBucket(key);
+    if (!bucket) return 0;
+    if (from < 0 || from >= bucket.length || count <= 0) return 0;
+    const actual = Math.min(count, bucket.length - from);
+    const insertAt = Math.max(0, Math.min(to, bucket.length - actual));
     if (insertAt === from) return 0;
-    const block = list.splice(from, actual);
-    list.splice(insertAt, 0, ...block);
+    const block = bucket.splice(from, actual);
+    bucket.splice(insertAt, 0, ...block);
     this.emitUpdate([key]);
     return actual;
   }
   resetSlots(key, slots) {
     if (slots.length === 0) {
-      if (this.store.getOneByKey(key) !== void 0) {
-        this.store.removeOneByKey(key);
+      const bucket2 = this.arrayStore.findBucket(key);
+      if (bucket2 && bucket2.length > 0) {
+        bucket2.length = 0;
+        this.arrayStore.releaseBucket(bucket2);
         this.emitUpdate([key]);
       }
       return;
     }
-    this.store.setOneByKey(key, slots.slice());
+    const bucket = this.arrayStore.getOrReserveBucket(key);
+    bucket.length = 0;
+    for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
+    this.arrayStore.retainBucket(bucket);
     this.emitUpdate([key]);
   }
-  getOrCreateList(key) {
-    let list = this.store.getOneByKey(key);
-    if (!list) {
-      list = [];
-      this.store.setOneByKey(key, list);
-    }
-    return list;
-  }
 };
 
 // src/core/OIMCollectionIndexManualOrderedArrayBased.ts
 var OIMCollectionIndexManualOrderedArrayBased = class extends OIMIndexManualOrderedArrayBased {
   constructor(opts) {
     super();
-    this.resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.resolveSlot;
+    this.getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.getSlot;
   }
   push(key, pk) {
-    return this.pushSlot(key, this.resolveRequiredSlot(pk));
+    return this.pushSlot(key, this.getRequiredSlot(pk));
   }
   insertAt(key, index, pk) {
-    return this.insertSlotAt(key, index, this.resolveRequiredSlot(pk));
+    return this.insertSlotAt(key, index, this.getRequiredSlot(pk));
   }
   reset(key, pks) {
-    this.resetSlots(key, this.resolveSlots(pks));
+    this.resetSlots(key, this.getRequiredSlots(pks));
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -1536,26 +1674,25 @@ var OIMCollectionIndexManualOrderedArrayBased = class extends OIMIndexManualOrde
   getEntitiesByKeys(keys) {
     return super.getEntitiesByKeys(keys);
   }
-  resolvePk(pk) {
-    return this.resolveRequiredSlot(pk);
+  // Gets the slot for a pk, throwing if the (custom) getter has none — this
+  // ordered index requires a real slot to place in order.
+  getRequiredSlot(pk) {
+    const slot = this.getSlot(pk);
+    if (!slot) {
+      throw new Error(
+        `[OIMCollectionIndexManualOrderedArrayBased]: no slot for PK "${String(pk)}".`
+      );
+    }
+    return slot;
   }
-  resolveSlots(pks) {
+  getRequiredSlots(pks) {
     const slots = [];
     slots.length = pks.length;
     for (let i = 0; i < pks.length; i++) {
-      slots[i] = this.resolveRequiredSlot(pks[i]);
+      slots[i] = this.getRequiredSlot(pks[i]);
     }
     return slots;
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
-    if (!slot) {
-      throw new Error(
-        `[OIMCollectionIndexManualOrderedArrayBased]: Unable to resolve slot for PK "${String(pk)}".`
-      );
-    }
-    return slot;
-  }
 };
 
 // src/enums/EOIMEventQueueEventType.ts
@@ -1974,18 +2111,18 @@ var OIMOrderedListCommandStream = class extends OIMOrderedListCommandBuffer {
 var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandStream {
   constructor(queue, opts) {
     const index = opts.index ?? new OIMCollectionIndexManualOrderedArrayBased(
-      opts.collection !== void 0 ? { collection: opts.collection } : { resolveSlot: opts.resolveSlot }
+      opts.collection !== void 0 ? { collection: opts.collection } : { getSlot: opts.getSlot }
     );
     super(queue, index);
     this.index = index;
   }
   push(key, pk) {
-    const slot = this.resolvePk(pk);
+    const slot = this.getRequiredSlot(pk);
     const index = this.index.pushSlot(key, slot);
     this.appendCommand(key, { type: "insert", index, item: slot });
   }
   insertAt(key, index, pk) {
-    const slot = this.resolvePk(pk);
+    const slot = this.getRequiredSlot(pk);
     const safeIndex = this.index.insertSlotAt(key, index, slot);
     this.appendCommand(key, {
       type: "insert",
@@ -1995,7 +2132,7 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
   }
   /** Replace the element at `index` with the slot for `pk`, in place. */
   setAt(key, index, pk) {
-    const slot = this.resolvePk(pk);
+    const slot = this.getRequiredSlot(pk);
     const safeIndex = this.index.setSlotAt(key, index, slot);
     if (safeIndex < 0) return;
     this.appendCommand(key, {
@@ -2005,7 +2142,7 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
     });
   }
   set(key, pks) {
-    const slots = pks.map((pk) => this.resolvePk(pk));
+    const slots = pks.map((pk) => this.getRequiredSlot(pk));
     this.index.resetSlots(key, slots);
     this.appendResetCommand(key, slots);
   }
@@ -2017,8 +2154,8 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
   getEntitiesByKey(key) {
     return this.index.getEntitiesByKey(key);
   }
-  resolvePk(pk) {
-    return this.index.resolvePk(
+  getRequiredSlot(pk) {
+    return this.index.getRequiredSlot(
       pk
     );
   }
@@ -2030,43 +2167,68 @@ var OIMIndexManualArrayBased = class extends OIMIndexArrayBased {
     super(options);
   }
   setSlots(key, slots) {
-    const hasChanges = this.setSlotsWithComparison(key, slots);
-    if (hasChanges) {
-      this.emitUpdateOne(key);
-    }
+    const bucket = this.arrayStore.getOrReserveBucket(key);
+    if (this.bucketMatchesComparator(bucket, slots)) return;
+    bucket.length = 0;
+    for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
+    if (bucket.length > 0) this.arrayStore.retainBucket(bucket);
+    else this.arrayStore.releaseBucket(bucket);
+    this.emitBucketChanged(bucket);
   }
   /**
-   * Appends pre-deduplicated slots to a key's bucket IN PLACE (no copy of the
-   * existing bucket) and emits once. Callers own dedup (so this stays O(added),
-   * not O(bucket)); used by collection-bound indexes for fast `addPks`.
+   * Appends pre-deduplicated slots to a key's bucket IN PLACE and emits once.
+   * O(added); callers own dedup.
    */
   appendSlots(key, slots) {
     if (slots.length === 0) return;
-    let bucket = this.store.getOneByKey(key);
-    if (!bucket) {
-      bucket = [];
-      this.store.setOneByKey(key, bucket);
-    }
+    const bucket = this.arrayStore.getOrReserveBucket(key);
     for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
-    this.emitUpdateOne(key);
+    this.arrayStore.retainBucket(bucket);
+    this.emitBucketChanged(bucket);
   }
   /**
-   * Clear all primary keys for a specific index key, or all keys if no key specified
+   * Clear all primary keys for a specific index key, or all keys if none given.
    */
   clear(key) {
     if (key === void 0) {
-      const allKeys = this.store.getAllKeys();
+      const allKeys = this.arrayStore.getAllKeys();
       if (allKeys.length > 0) {
-        this.store.clear();
+        this.arrayStore.clear();
         this.emitUpdate(allKeys);
       }
     } else {
-      if (this.store.getOneByKey(key) !== void 0) {
-        this.store.removeOneByKey(key);
-        this.emitUpdateOne(key);
+      const bucket = this.arrayStore.findBucket(key);
+      if (bucket && bucket.length > 0) {
+        bucket.length = 0;
+        this.arrayStore.releaseBucket(bucket);
+        this.emitBucketChanged(bucket);
       }
     }
   }
+  /**
+   * Emit that a bucket changed. Base (non-reactive) path emits by key on the
+   * plain event emitter; the reactive subclass overrides this to mark the
+   * bucket carrier directly (O(1), no key→carrier lookup).
+   */
+  emitBucketChanged(bucket) {
+    this.emitUpdateOne(bucket.key);
+  }
+};
+
+// src/core/OIMBucketCarrierProvider.ts
+var OIMBucketCarrierProvider = class {
+  constructor(store) {
+    this.store = store;
+  }
+  getOrReserveCarrier(key) {
+    return this.store.getOrReserveBucket(key);
+  }
+  findCarrier(key) {
+    return this.store.findBucket(key);
+  }
+  onCarrierEmptied(carrier) {
+    this.store.dropIfReserved(carrier.key);
+  }
 };
 
 // src/core/OIMReactiveIndexManualArrayBased.ts
@@ -2075,6 +2237,10 @@ var OIMIndexManualArrayBasedReactive = class extends OIMIndexManualArrayBased {
     super(opts);
     this.updateEmitter = updateEmitter;
   }
+  // Deliver straight off the bucket the write just touched — O(1).
+  emitBucketChanged(bucket) {
+    this.updateEmitter.markUpdatedCarrier(bucket);
+  }
   emitUpdate(keys) {
     this.updateEmitter.markUpdatedKeys(keys);
   }
@@ -2084,12 +2250,15 @@ var OIMIndexManualArrayBasedReactive = class extends OIMIndexManualArrayBased {
 };
 var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased {
   constructor(queue, opts) {
-    super(queue, (updateEmitter) => {
-      return new OIMIndexManualArrayBasedReactive(
-        updateEmitter,
-        opts?.indexOptions
-      );
-    });
+    const store = opts?.indexOptions?.store ?? new OIMIndexStoreMapDrivenArrayBased();
+    super(
+      queue,
+      (updateEmitter) => new OIMIndexManualArrayBasedReactive(updateEmitter, {
+        comparePks: opts?.indexOptions?.comparePks,
+        store
+      }),
+      () => new OIMBucketCarrierProvider(store)
+    );
   }
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
@@ -2105,50 +2274,61 @@ var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased
 // src/core/OIMReactiveCollectionIndexManualArrayBased.ts
 var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexManualArrayBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
     super(queue, {
       indexOptions: opts.indexOptions
     });
-    // Persistent per-key pk membership for O(1) `addPks` dedup (avoids rebuilding
-    // a Set from the whole bucket on every call). Kept in sync by setSlots/clear.
-    this.pksByKey = /* @__PURE__ */ new Map();
-    this.resolveSlot = resolveSlot;
+    // Persistent per-key membership for O(1) `addPks` dedup, keyed by the
+    // canonical slot reference (correct for composite pks with a native Set — no
+    // content-addressing needed, since slots are one reference per logical key).
+    this.slotsByKey = /* @__PURE__ */ new Map();
+    this.getSlot = getSlot;
+    this.findSlotForRemoval = opts.collection !== void 0 ? (pk) => opts.collection.findSlotByPk(pk) : opts.getSlot;
   }
   setPks(key, pks) {
-    const pkSet = /* @__PURE__ */ new Set();
-    for (let i = 0; i < pks.length; i++) pkSet.add(pks[i]);
-    this.pksByKey.set(key, pkSet);
-    super.setSlots(key, this.resolveSlots(pks));
+    const slots = this.getSlotsOrTransient(pks);
+    this.slotsByKey.set(key, new Set(slots));
+    super.setSlots(key, slots);
   }
   addPks(key, pks) {
     if (pks.length === 0) return;
-    const pkSet = this.membershipOf(key);
+    const slotSet = this.membershipOf(key);
     const newSlots = [];
     for (const pk of pks) {
-      if (pkSet.has(pk)) continue;
-      pkSet.add(pk);
-      newSlots.push(this.resolveRequiredSlot(pk));
+      const slot = this.getSlotOrTransient(pk);
+      if (slotSet.has(slot)) continue;
+      slotSet.add(slot);
+      newSlots.push(slot);
     }
     if (newSlots.length > 0) this.appendSlots(key, newSlots);
   }
   removePks(key, pks) {
     if (pks.length === 0) return;
-    const pksToRemove = new Set(pks);
+    const slotsToRemove = /* @__PURE__ */ new Set();
+    const pksToRemove = /* @__PURE__ */ new Set();
+    for (let i = 0; i < pks.length; i++) {
+      const slot = this.findSlotForRemoval(pks[i]);
+      if (slot) slotsToRemove.add(slot);
+      else pksToRemove.add(pks[i]);
+    }
     const existingSlots = this.index.getSlotsByKey(key);
-    const nextSlots = existingSlots.filter(
-      (slot) => !pksToRemove.has(slot.pk)
-    );
-    if (nextSlots.length === existingSlots.length) return;
-    const pkSet = this.pksByKey.get(key);
-    if (pkSet) {
-      for (let i = 0; i < pks.length; i++) pkSet.delete(pks[i]);
+    const slotSet = this.slotsByKey.get(key);
+    const nextSlots = [];
+    for (let i = 0; i < existingSlots.length; i++) {
+      const slot = existingSlots[i];
+      if (slotsToRemove.has(slot) || pksToRemove.has(slot.pk)) {
+        slotSet?.delete(slot);
+      } else {
+        nextSlots.push(slot);
+      }
     }
+    if (nextSlots.length === existingSlots.length) return;
     if (nextSlots.length === 0) this.clear(key);
     else super.setSlots(key, nextSlots);
   }
   clear(key) {
-    if (key === void 0) this.pksByKey.clear();
-    else this.pksByKey.delete(key);
+    if (key === void 0) this.slotsByKey.clear();
+    else this.slotsByKey.delete(key);
     super.clear(key);
   }
   /**
@@ -2156,16 +2336,12 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
    * stays correct even if slots were set through a lower-level path.
    */
   membershipOf(key) {
-    let pkSet = this.pksByKey.get(key);
-    if (!pkSet) {
-      pkSet = /* @__PURE__ */ new Set();
-      const existing = this.index.getSlotsByKey(key);
-      for (let i = 0; i < existing.length; i++) {
-        pkSet.add(existing[i].pk);
-      }
-      this.pksByKey.set(key, pkSet);
+    let slotSet = this.slotsByKey.get(key);
+    if (!slotSet) {
+      slotSet = new Set(this.index.getSlotsByKey(key));
+      this.slotsByKey.set(key, slotSet);
     }
-    return pkSet;
+    return slotSet;
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -2173,16 +2349,16 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
   getEntitiesByKeys(keys) {
     return super.getEntitiesByKeys(keys);
   }
-  resolveSlots(pks) {
+  getSlotsOrTransient(pks) {
     const slots = [];
     slots.length = pks.length;
     for (let i = 0; i < pks.length; i++) {
-      slots[i] = this.resolveRequiredSlot(pks[i]);
+      slots[i] = this.getSlotOrTransient(pks[i]);
     }
     return slots;
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
+  getSlotOrTransient(pk) {
+    const slot = this.getSlot(pk);
     if (!slot) return { pk, item: void 0 };
     return slot;
   }
@@ -2194,22 +2370,101 @@ var OIMIndexManualSetBased = class extends OIMIndexSetBased {
     super(options);
   }
   setSlots(key, slots) {
-    const hasChanges = this.setSlotsWithComparison(key, new Set(slots));
-    if (hasChanges) {
-      this.emitUpdateOne(key);
+    const bucket = this.setStore.getOrReserveBucket(key);
+    this.replaceBucketContents(bucket, slots);
+  }
+  // --- pk-oriented writes: resolve the bucket ONCE and use its own membership
+  // (pk → slot) for dedup/removal, so a composite (trie) key is walked a single
+  // time instead of once for the bucket and once for a separate membership map.
+  setPks(key, pks, getSlot) {
+    const bucket = this.setStore.getOrReserveBucket(key);
+    const slots = [];
+    for (let i = 0; i < pks.length; i++) slots.push(getSlot(pks[i]));
+    this.replaceBucketContents(bucket, slots);
+    const membership = bucket.membership ?? (bucket.membership = /* @__PURE__ */ new Map());
+    membership.clear();
+    for (let i = 0; i < slots.length; i++) {
+      if (!membership.has(slots[i].pk)) {
+        membership.set(slots[i].pk, slots[i]);
+      }
+    }
+  }
+  addPks(key, pks, getSlot) {
+    if (pks.length === 0) return;
+    const bucket = this.setStore.getOrReserveBucket(key);
+    const membership = this.membershipOf(bucket);
+    let changed = false;
+    for (let i = 0; i < pks.length; i++) {
+      const slot = getSlot(pks[i]);
+      if (membership.has(slot.pk)) continue;
+      membership.set(slot.pk, slot);
+      if (!bucket.has(slot)) {
+        bucket.add(slot);
+        changed = true;
+      }
     }
+    if (!changed) return;
+    this.setStore.retainBucket(bucket);
+    this.emitBucketChanged(bucket);
   }
   /**
-   * Adds slots to a key's bucket IN PLACE (no copy of the existing Set) and
-   * emits once. O(added). Used by collection-bound indexes for fast `addPks`.
+   * Removes by pk. `pks` must be canonical `slot.pk` references (membership is
+   * keyed by them): for primitive pks that is just the pk; a collection-bound
+   * composite index canonicalizes raw pks to `slot.pk` before calling this.
+   */
+  removePks(key, pks) {
+    if (pks.length === 0) return;
+    const bucket = this.setStore.findBucket(key);
+    if (!bucket || bucket.size === 0) return;
+    const membership = this.membershipOf(bucket);
+    let changed = false;
+    for (let i = 0; i < pks.length; i++) {
+      const slot = membership.get(pks[i]);
+      if (slot) {
+        membership.delete(pks[i]);
+        if (bucket.delete(slot)) changed = true;
+      }
+    }
+    if (!changed) return;
+    if (bucket.size === 0) this.setStore.releaseBucket(bucket);
+    this.emitBucketChanged(bucket);
+  }
+  /**
+   * The bucket's pk → slot membership, lazily created and seeded from the
+   * bucket's current slots (so it stays correct even if slots were written
+   * through the lower-level `setSlots` path).
+   */
+  membershipOf(bucket) {
+    let membership = bucket.membership;
+    if (!membership) {
+      membership = /* @__PURE__ */ new Map();
+      bucket.membership = membership;
+    }
+    if (membership.size === 0 && bucket.size > 0) {
+      for (const slot of bucket) membership.set(slot.pk, slot);
+    }
+    return membership;
+  }
+  replaceBucketContents(bucket, slots) {
+    if (this.comparePks) {
+      const newSet = slots instanceof Set ? slots : new Set(slots);
+      if (this.bucketMatchesComparator(bucket, newSet)) return;
+      bucket.clear();
+      for (const slot of newSet) bucket.add(slot);
+    } else {
+      bucket.clear();
+      for (const slot of slots) bucket.add(slot);
+    }
+    if (bucket.size > 0) this.setStore.retainBucket(bucket);
+    else this.setStore.releaseBucket(bucket);
+    this.emitBucketChanged(bucket);
+  }
+  /**
+   * Adds slots to a key's bucket IN PLACE and emits once. O(added).
    */
   addSlots(key, slots) {
     if (slots.length === 0) return;
-    let bucket = this.store.getOneByKey(key);
-    if (!bucket) {
-      bucket = /* @__PURE__ */ new Set();
-      this.store.setOneByKey(key, bucket);
-    }
+    const bucket = this.setStore.getOrReserveBucket(key);
     let changed = false;
     for (let i = 0; i < slots.length; i++) {
       if (!bucket.has(slots[i])) {
@@ -2217,25 +2472,27 @@ var OIMIndexManualSetBased = class extends OIMIndexSetBased {
         changed = true;
       }
     }
-    if (changed) this.emitUpdateOne(key);
+    if (!changed) return;
+    this.setStore.retainBucket(bucket);
+    this.emitBucketChanged(bucket);
   }
   /**
    * Removes slots from a key's bucket IN PLACE (O(removed)) and emits once.
    */
   removeSlots(key, slots) {
     if (slots.length === 0) return;
-    const bucket = this.store.getOneByKey(key);
+    const bucket = this.setStore.findBucket(key);
     if (!bucket) return;
     let changed = false;
     for (let i = 0; i < slots.length; i++) {
       if (bucket.delete(slots[i])) changed = true;
     }
     if (!changed) return;
-    if (bucket.size === 0) this.store.removeOneByKey(key);
-    this.emitUpdateOne(key);
+    if (bucket.size === 0) this.setStore.releaseBucket(bucket);
+    this.emitBucketChanged(bucket);
   }
   /**
-   * Clear all primary keys for a specific index key, or all keys if no key specified
+   * Clear all primary keys for a specific index key, or all keys if none given.
    */
   clear(key) {
     if (key === void 0) {
@@ -2245,12 +2502,22 @@ var OIMIndexManualSetBased = class extends OIMIndexSetBased {
         this.emitUpdate(allKeys);
       }
     } else {
-      if (this.store.getOneByKey(key) !== void 0) {
-        this.store.removeOneByKey(key);
-        this.emitUpdateOne(key);
+      const bucket = this.setStore.findBucket(key);
+      if (bucket && bucket.size > 0) {
+        bucket.clear();
+        this.setStore.releaseBucket(bucket);
+        this.emitBucketChanged(bucket);
       }
     }
   }
+  /**
+   * Emit that a bucket changed. Base (non-reactive) path emits by key on the
+   * plain event emitter; the reactive subclass overrides this to mark the
+   * bucket carrier directly (O(1), no key→carrier lookup).
+   */
+  emitBucketChanged(bucket) {
+    this.emitUpdateOne(bucket.key);
+  }
 };
 
 // src/core/OIMReactiveIndexManualSetBased.ts
@@ -2259,6 +2526,12 @@ var OIMIndexManualSetBasedReactive = class extends OIMIndexManualSetBased {
     super(opts);
     this.updateEmitter = updateEmitter;
   }
+  // Deliver straight off the bucket the write just touched — O(1), no
+  // key→carrier lookup (the whole point of bucket-as-carrier).
+  emitBucketChanged(bucket) {
+    this.updateEmitter.markUpdatedCarrier(bucket);
+  }
+  // clear(all) still emits by key set (rare path).
   emitUpdate(keys) {
     this.updateEmitter.markUpdatedKeys(keys);
   }
@@ -2268,12 +2541,15 @@ var OIMIndexManualSetBasedReactive = class extends OIMIndexManualSetBased {
 };
 var OIMReactiveIndexManualSetBased = class extends OIMReactiveIndexSetBased {
   constructor(queue, opts) {
-    super(queue, (updateEmitter) => {
-      return new OIMIndexManualSetBasedReactive(
-        updateEmitter,
-        opts?.indexOptions
-      );
-    });
+    const store = opts?.indexOptions?.store ?? new OIMIndexStoreMapDrivenSetBased();
+    super(
+      queue,
+      (updateEmitter) => new OIMIndexManualSetBasedReactive(updateEmitter, {
+        comparePks: opts?.indexOptions?.comparePks,
+        store
+      }),
+      () => new OIMBucketCarrierProvider(store)
+    );
   }
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
@@ -2292,73 +2568,439 @@ var OIMReactiveIndexManualSetBased = class extends OIMReactiveIndexSetBased {
 // src/core/OIMReactiveCollectionIndexManualSetBased.ts
 var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexManualSetBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
     super(queue, {
       indexOptions: opts.indexOptions
     });
-    // Persistent per-key pk → slot map for O(1) add (dedup) and O(1) remove
-    // (slot lookup by pk). Kept in sync by setPks/addPks/removePks/clear.
-    this.slotByPk = /* @__PURE__ */ new Map();
-    this.resolveSlot = resolveSlot;
+    // Bound once so the hot pk-write path passes a stable function (no per-call
+    // closure allocation).
+    this.getSlotOrTransient = (pk) => {
+      const slot = this.getSlot(pk);
+      if (!slot) return { pk, item: void 0 };
+      return slot;
+    };
+    this.getSlot = getSlot;
+    this.findSlotForRemoval = opts.collection !== void 0 ? (pk) => opts.collection.findSlotByPk(pk) : opts.getSlot;
   }
   setPks(key, pks) {
-    const map = /* @__PURE__ */ new Map();
-    const slots = [];
+    this.index.setPks(key, pks, this.getSlotOrTransient);
+  }
+  addPks(key, pks) {
+    this.index.addPks(key, pks, this.getSlotOrTransient);
+  }
+  removePks(key, pks) {
+    const canonical = [];
     for (let i = 0; i < pks.length; i++) {
-      const pk = pks[i];
-      const slot = this.resolveRequiredSlot(pk);
-      if (!map.has(pk)) map.set(pk, slot);
-      slots.push(slot);
+      const slot = this.findSlotForRemoval(pks[i]);
+      canonical.push(slot ? slot.pk : pks[i]);
     }
-    this.slotByPk.set(key, map);
-    super.setSlots(key, slots);
+    this.index.removePks(key, canonical);
+  }
+  getEntitiesByKey(key) {
+    return super.getEntitiesByKey(key);
+  }
+  getEntitiesByKeys(keys) {
+    return super.getEntitiesByKeys(keys);
+  }
+};
+
+// src/core/OIMTrieMap.ts
+var OIMTrieMap = class {
+  constructor() {
+    this.root = { hasValue: false };
+    this._size = 0;
+  }
+  /** Number of stored paths (terminal nodes), not the number of trie nodes. */
+  get size() {
+    return this._size;
+  }
+  set(path, value) {
+    let node = this.root;
+    for (let i = 0; i < path.length; i++) {
+      let children = node.children;
+      if (!children) {
+        children = /* @__PURE__ */ new Map();
+        node.children = children;
+      }
+      let next = children.get(path[i]);
+      if (!next) {
+        next = { hasValue: false };
+        children.set(path[i], next);
+      }
+      node = next;
+    }
+    if (!node.hasValue) {
+      node.hasValue = true;
+      this._size++;
+    }
+    node.value = value;
+  }
+  get(path) {
+    const node = this.findNode(path);
+    return node && node.hasValue ? node.value : void 0;
+  }
+  has(path) {
+    const node = this.findNode(path);
+    return !!node && node.hasValue;
+  }
+  delete(path) {
+    const parents = [];
+    let node = this.root;
+    for (let i = 0; i < path.length; i++) {
+      const next = node.children?.get(path[i]);
+      if (!next) return false;
+      parents.push(node);
+      node = next;
+    }
+    if (!node.hasValue) return false;
+    node.hasValue = false;
+    node.value = void 0;
+    this._size--;
+    let child = node;
+    for (let i = parents.length - 1; i >= 0; i--) {
+      if (child.hasValue || child.children && child.children.size > 0) {
+        break;
+      }
+      const parent = parents[i];
+      parent.children.delete(path[i]);
+      if (parent.children.size === 0) parent.children = void 0;
+      child = parent;
+    }
+    return true;
+  }
+  clear() {
+    this.root.children = void 0;
+    this.root.value = void 0;
+    this.root.hasValue = false;
+    this._size = 0;
+  }
+  /** Depth-first iteration over `[path, value]` for every stored path. */
+  *entries() {
+    const stack = [{ node: this.root, path: [] }];
+    while (stack.length > 0) {
+      const frame = stack.pop();
+      const { node, path } = frame;
+      if (node.hasValue) {
+        yield [path, node.value];
+      }
+      if (node.children) {
+        for (const [segment, child] of node.children) {
+          stack.push({ node: child, path: [...path, segment] });
+        }
+      }
+    }
+  }
+  *keys() {
+    for (const [path] of this.entries()) yield path;
+  }
+  *values() {
+    for (const [, value] of this.entries()) yield value;
+  }
+  findNode(path) {
+    let node = this.root;
+    for (let i = 0; i < path.length; i++) {
+      node = node.children?.get(path[i]);
+      if (!node) return void 0;
+    }
+    return node;
+  }
+};
+
+// src/core/OIMIndexStoreTrieDrivenSetBased.ts
+var OIMIndexStoreTrieDrivenSetBased = class extends OIMIndexStoreSetBased {
+  constructor() {
+    super(...arguments);
+    this.slots = new OIMTrieMap();
+    this.reservedBuckets = new OIMTrieMap();
+  }
+  getOrReserveBucket(key) {
+    const live = this.slots.get(key);
+    if (live) return live;
+    let reserved = this.reservedBuckets.get(key);
+    if (!reserved) {
+      reserved = new OIMKeyedBucketSetBased(key);
+      this.reservedBuckets.set(key, reserved);
+    }
+    return reserved;
+  }
+  findBucket(key) {
+    return this.slots.get(key) ?? this.reservedBuckets.get(key);
+  }
+  retainBucket(bucket) {
+    if (bucket.size === 0) return;
+    this.reservedBuckets.delete(bucket.key);
+    if (!this.slots.has(bucket.key)) this.slots.set(bucket.key, bucket);
+  }
+  releaseBucket(bucket) {
+    if (bucket.size > 0) return;
+    this.slots.delete(bucket.key);
+    if (bucket.hasSubscribers()) {
+      this.reservedBuckets.set(bucket.key, bucket);
+    } else {
+      this.reservedBuckets.delete(bucket.key);
+    }
+  }
+  dropIfReserved(key) {
+    const reserved = this.reservedBuckets.get(key);
+    if (reserved && reserved.size === 0 && !reserved.hasSubscribers()) {
+      this.reservedBuckets.delete(key);
+    }
+  }
+  setOneByKey(key, slots) {
+    const bucket = this.getOrReserveBucket(key);
+    if (bucket !== slots) {
+      bucket.clear();
+      for (const slot of slots) bucket.add(slot);
+    }
+    if (bucket.size > 0) this.retainBucket(bucket);
+    else this.releaseBucket(bucket);
+  }
+  removeOneByKey(key) {
+    this.slots.delete(key);
+    this.reservedBuckets.delete(key);
+  }
+  removeManyByKeys(keys) {
+    for (let i = 0; i < keys.length; i++) {
+      this.slots.delete(keys[i]);
+      this.reservedBuckets.delete(keys[i]);
+    }
+  }
+  getOneByKey(key) {
+    return this.slots.get(key);
+  }
+  getManyByKeys(keys) {
+    const result = /* @__PURE__ */ new Map();
+    for (let i = 0; i < keys.length; i++) {
+      const slots = this.slots.get(keys[i]);
+      if (slots !== void 0) result.set(keys[i], slots);
+    }
+    return result;
+  }
+  getAllKeys() {
+    return Array.from(this.slots.keys());
+  }
+  getAll() {
+    const result = /* @__PURE__ */ new Map();
+    for (const [path, bucket] of this.slots.entries()) {
+      result.set(path, bucket);
+    }
+    return result;
+  }
+  countAll() {
+    return this.slots.size;
+  }
+  clear() {
+    for (const bucket of this.slots.values()) {
+      bucket.clear();
+      if (bucket.hasSubscribers()) {
+        this.reservedBuckets.set(bucket.key, bucket);
+      }
+    }
+    this.slots.clear();
+  }
+};
+
+// src/core/OIMReactiveCollectionIndexCompositeTrieSetBased.ts
+var OIMReactiveCollectionIndexCompositeTrieSetBased = class extends OIMReactiveIndexManualSetBased {
+  constructor(queue, opts) {
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
+    super(queue, {
+      indexOptions: {
+        comparePks: opts.indexOptions?.comparePks,
+        store: opts.indexOptions?.store ?? new OIMIndexStoreTrieDrivenSetBased()
+      }
+    });
+    this.getSlotOrTransient = (pk) => {
+      const slot = this.getSlot(pk);
+      if (!slot) return { pk, item: void 0 };
+      return slot;
+    };
+    this.getSlot = getSlot;
+    this.findSlotForRemoval = opts.collection !== void 0 ? (pk) => opts.collection.findSlotByPk(pk) : opts.getSlot;
+  }
+  setPks(key, pks) {
+    this.index.setPks(key, pks, this.getSlotOrTransient);
+  }
+  addPks(key, pks) {
+    this.index.addPks(key, pks, this.getSlotOrTransient);
+  }
+  removePks(key, pks) {
+    const canonical = [];
+    for (let i = 0; i < pks.length; i++) {
+      const slot = this.findSlotForRemoval(pks[i]);
+      canonical.push(slot ? slot.pk : pks[i]);
+    }
+    this.index.removePks(key, canonical);
+  }
+  getEntitiesByKey(key) {
+    return super.getEntitiesByKey(key);
+  }
+  getEntitiesByKeys(keys) {
+    return super.getEntitiesByKeys(keys);
+  }
+};
+
+// src/core/OIMIndexStoreTrieDrivenArrayBased.ts
+var OIMIndexStoreTrieDrivenArrayBased = class extends OIMIndexStoreArrayBased {
+  constructor() {
+    super(...arguments);
+    this.slots = new OIMTrieMap();
+    this.reservedBuckets = new OIMTrieMap();
+  }
+  getOrReserveBucket(key) {
+    const live = this.slots.get(key);
+    if (live) return live;
+    let reserved = this.reservedBuckets.get(key);
+    if (!reserved) {
+      reserved = new OIMKeyedBucketArrayBased(key);
+      this.reservedBuckets.set(key, reserved);
+    }
+    return reserved;
+  }
+  findBucket(key) {
+    return this.slots.get(key) ?? this.reservedBuckets.get(key);
+  }
+  retainBucket(bucket) {
+    if (bucket.length === 0) return;
+    this.reservedBuckets.delete(bucket.key);
+    if (!this.slots.has(bucket.key)) this.slots.set(bucket.key, bucket);
+  }
+  releaseBucket(bucket) {
+    if (bucket.length > 0) return;
+    this.slots.delete(bucket.key);
+    if (bucket.hasSubscribers()) {
+      this.reservedBuckets.set(bucket.key, bucket);
+    } else {
+      this.reservedBuckets.delete(bucket.key);
+    }
+  }
+  dropIfReserved(key) {
+    const reserved = this.reservedBuckets.get(key);
+    if (reserved && reserved.length === 0 && !reserved.hasSubscribers()) {
+      this.reservedBuckets.delete(key);
+    }
+  }
+  setOneByKey(key, slots) {
+    const bucket = this.getOrReserveBucket(key);
+    if (bucket !== slots) {
+      bucket.length = 0;
+      for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
+    }
+    if (bucket.length > 0) this.retainBucket(bucket);
+    else this.releaseBucket(bucket);
+  }
+  removeOneByKey(key) {
+    this.slots.delete(key);
+    this.reservedBuckets.delete(key);
+  }
+  removeManyByKeys(keys) {
+    for (let i = 0; i < keys.length; i++) {
+      this.slots.delete(keys[i]);
+      this.reservedBuckets.delete(keys[i]);
+    }
+  }
+  getOneByKey(key) {
+    return this.slots.get(key);
+  }
+  getManyByKeys(keys) {
+    const result = /* @__PURE__ */ new Map();
+    for (let i = 0; i < keys.length; i++) {
+      const slots = this.slots.get(keys[i]);
+      if (slots !== void 0) result.set(keys[i], slots);
+    }
+    return result;
+  }
+  getAllKeys() {
+    return Array.from(this.slots.keys());
+  }
+  getAll() {
+    const result = /* @__PURE__ */ new Map();
+    for (const [path, bucket] of this.slots.entries()) {
+      result.set(path, bucket);
+    }
+    return result;
+  }
+  countAll() {
+    return this.slots.size;
+  }
+  clear() {
+    for (const bucket of this.slots.values()) {
+      bucket.length = 0;
+      if (bucket.hasSubscribers()) {
+        this.reservedBuckets.set(bucket.key, bucket);
+      }
+    }
+    this.slots.clear();
+  }
+};
+
+// src/core/OIMReactiveCollectionIndexCompositeTrieArrayBased.ts
+var OIMReactiveCollectionIndexCompositeTrieArrayBased = class extends OIMReactiveIndexManualArrayBased {
+  constructor(queue, opts) {
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
+    super(queue, {
+      indexOptions: {
+        comparePks: opts.indexOptions?.comparePks,
+        store: opts.indexOptions?.store ?? new OIMIndexStoreTrieDrivenArrayBased()
+      }
+    });
+    // Persistent per-key-path pk membership for O(1) `addPks` dedup. Trie-keyed
+    // so a rebuilt key path matches by content.
+    this.pksByKey = new OIMTrieMap();
+    this.getSlot = getSlot;
+  }
+  setPks(key, pks) {
+    const pkSet = /* @__PURE__ */ new Set();
+    for (let i = 0; i < pks.length; i++) pkSet.add(pks[i]);
+    this.pksByKey.set(key, pkSet);
+    super.setSlots(key, this.getSlotsOrTransient(pks));
   }
   addPks(key, pks) {
     if (pks.length === 0) return;
-    const map = this.membershipOf(key);
+    const pkSet = this.membershipOf(key);
     const newSlots = [];
     for (const pk of pks) {
-      if (map.has(pk)) continue;
-      const slot = this.resolveRequiredSlot(pk);
-      map.set(pk, slot);
-      newSlots.push(slot);
+      if (pkSet.has(pk)) continue;
+      pkSet.add(pk);
+      newSlots.push(this.getSlotOrTransient(pk));
     }
-    if (newSlots.length > 0) this.addSlots(key, newSlots);
+    if (newSlots.length > 0) this.appendSlots(key, newSlots);
   }
   removePks(key, pks) {
     if (pks.length === 0) return;
-    const map = this.membershipOf(key);
-    if (map.size === 0) return;
-    const removed = [];
-    for (const pk of pks) {
-      const slot = map.get(pk);
-      if (slot) {
-        map.delete(pk);
-        removed.push(slot);
-      }
+    const pksToRemove = new Set(pks);
+    const existingSlots = this.index.getSlotsByKey(key);
+    const nextSlots = existingSlots.filter(
+      (slot) => !pksToRemove.has(slot.pk)
+    );
+    if (nextSlots.length === existingSlots.length) return;
+    const pkSet = this.pksByKey.get(key);
+    if (pkSet) {
+      for (let i = 0; i < pks.length; i++) pkSet.delete(pks[i]);
     }
-    if (removed.length === 0) return;
-    if (map.size === 0) this.slotByPk.delete(key);
-    this.removeSlots(key, removed);
+    if (nextSlots.length === 0) this.clear(key);
+    else super.setSlots(key, nextSlots);
   }
   clear(key) {
-    if (key === void 0) this.slotByPk.clear();
-    else this.slotByPk.delete(key);
+    if (key === void 0) this.pksByKey.clear();
+    else this.pksByKey.delete(key);
     super.clear(key);
   }
   /**
-   * The pk→slot map for a key, lazily seeded from the current bucket so it
-   * stays correct even if slots were set through a lower-level path.
+   * The membership set for a key path, lazily seeded from the current bucket so
+   * it stays correct even if slots were set through a lower-level path.
    */
   membershipOf(key) {
-    let map = this.slotByPk.get(key);
-    if (!map) {
-      map = /* @__PURE__ */ new Map();
+    let pkSet = this.pksByKey.get(key);
+    if (!pkSet) {
+      pkSet = /* @__PURE__ */ new Set();
       const existing = this.index.getSlotsByKey(key);
-      for (const slot of existing) map.set(slot.pk, slot);
-      this.slotByPk.set(key, map);
+      for (let i = 0; i < existing.length; i++) {
+        pkSet.add(existing[i].pk);
+      }
+      this.pksByKey.set(key, pkSet);
     }
-    return map;
+    return pkSet;
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -2366,8 +3008,16 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   getEntitiesByKeys(keys) {
     return super.getEntitiesByKeys(keys);
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
+  getSlotsOrTransient(pks) {
+    const slots = [];
+    slots.length = pks.length;
+    for (let i = 0; i < pks.length; i++) {
+      slots[i] = this.getSlotOrTransient(pks[i]);
+    }
+    return slots;
+  }
+  getSlotOrTransient(pk) {
+    const slot = this.getSlot(pk);
     if (!slot) return { pk, item: void 0 };
     return slot;
   }
@@ -2680,20 +3330,20 @@ var OIMReactiveGlobalIndexManualArrayBased = class extends OIMReactiveGlobalInde
 // src/core/OIMReactiveCollectionGlobalIndexManualArrayBased.ts
 var OIMReactiveCollectionGlobalIndexManualArrayBased = class extends OIMReactiveGlobalIndexManualArrayBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
     super(queue, { indexOptions: opts.indexOptions });
     // Single pk membership set for O(1) `addPks` dedup. Lazily seeded from the
     // bucket so it stays correct even after a raw `setSlots` (e.g. derived
     // rebuild), matching the keyed index's `membershipOf`.
     this.membership = /* @__PURE__ */ new Set();
     this.membershipSeeded = false;
-    this.resolveSlot = resolveSlot;
+    this.getSlot = getSlot;
   }
   setPks(pks) {
     this.membership.clear();
     for (let i = 0; i < pks.length; i++) this.membership.add(pks[i]);
     this.membershipSeeded = true;
-    super.setSlots(this.resolveSlots(pks));
+    super.setSlots(this.getSlotsOrTransient(pks));
   }
   addPks(pks) {
     if (pks.length === 0) return;
@@ -2702,7 +3352,7 @@ var OIMReactiveCollectionGlobalIndexManualArrayBased = class extends OIMReactive
     for (const pk of pks) {
       if (membership.has(pk)) continue;
       membership.add(pk);
-      newSlots.push(this.resolveRequiredSlot(pk));
+      newSlots.push(this.getSlotOrTransient(pk));
     }
     if (newSlots.length > 0) super.appendSlots(newSlots);
   }
@@ -2739,16 +3389,16 @@ var OIMReactiveCollectionGlobalIndexManualArrayBased = class extends OIMReactive
   getEntities() {
     return super.getEntities();
   }
-  resolveSlots(pks) {
+  getSlotsOrTransient(pks) {
     const slots = [];
     slots.length = pks.length;
     for (let i = 0; i < pks.length; i++) {
-      slots[i] = this.resolveRequiredSlot(pks[i]);
+      slots[i] = this.getSlotOrTransient(pks[i]);
     }
     return slots;
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
+  getSlotOrTransient(pk) {
+    const slot = this.getSlot(pk);
     if (!slot) return { pk, item: void 0 };
     return slot;
   }
@@ -2828,18 +3478,18 @@ var OIMReactiveGlobalIndexManualSetBased = class extends OIMReactiveGlobalIndexS
 // src/core/OIMReactiveCollectionGlobalIndexManualSetBased.ts
 var OIMReactiveCollectionGlobalIndexManualSetBased = class extends OIMReactiveGlobalIndexManualSetBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    const getSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.getSlot;
     super(queue, { indexOptions: opts.indexOptions });
     this.membership = /* @__PURE__ */ new Map();
     this.membershipSeeded = false;
-    this.resolveSlot = resolveSlot;
+    this.getSlot = getSlot;
   }
   setPks(pks) {
     this.membership.clear();
     const slots = [];
     for (let i = 0; i < pks.length; i++) {
       const pk = pks[i];
-      const slot = this.resolveRequiredSlot(pk);
+      const slot = this.getSlotOrTransient(pk);
       if (!this.membership.has(pk)) this.membership.set(pk, slot);
       slots.push(slot);
     }
@@ -2852,7 +3502,7 @@ var OIMReactiveCollectionGlobalIndexManualSetBased = class extends OIMReactiveGl
     const newSlots = [];
     for (const pk of pks) {
       if (membership.has(pk)) continue;
-      const slot = this.resolveRequiredSlot(pk);
+      const slot = this.getSlotOrTransient(pk);
       membership.set(pk, slot);
       newSlots.push(slot);
     }
@@ -2891,8 +3541,8 @@ var OIMReactiveCollectionGlobalIndexManualSetBased = class extends OIMReactiveGl
   getEntities() {
     return super.getEntities();
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
+  getSlotOrTransient(pk) {
+    const slot = this.getSlot(pk);
     if (!slot) return { pk, item: void 0 };
     return slot;
   }
@@ -3071,6 +3721,30 @@ var OIMCollectionIndexFactory = class {
       indexOptions: opts.indexOptions
     });
   }
+  /**
+   * Composite (trie-backed) manual Set-based index keyed by an
+   * arbitrary-length key path, e.g. `setPks([userId, projectId, role], pks)`.
+   * Key paths are matched by content in O(arity) — no string concatenation,
+   * no separator collisions, each segment keeps its type. Primitive-keyed
+   * indexes are unaffected and keep their native-`Map` fast path.
+   */
+  compositeSetIndex(opts = {}) {
+    return new OIMReactiveCollectionIndexCompositeTrieSetBased(this.queue, {
+      collection: this.collection,
+      indexOptions: opts.indexOptions
+    });
+  }
+  /**
+   * Composite (trie-backed) manual Array-based (ordered) index keyed by an
+   * arbitrary-length key path, e.g. `setPks([channelId, threadId], pks)`.
+   * Ordered counterpart of `compositeSetIndex`.
+   */
+  compositeArrayIndex(opts = {}) {
+    return new OIMReactiveCollectionIndexCompositeTrieArrayBased(this.queue, {
+      collection: this.collection,
+      indexOptions: opts.indexOptions
+    });
+  }
   derivedSetIndex(selectIndexKeys, opts = {}) {
     return new OIMDerivedCollectionIndexSetBased(
       this.queue,
@@ -3277,7 +3951,7 @@ var OIMObject = class {
 var OIMReactiveObject = class extends OIMObject {
   constructor(queue, opts) {
     super(opts);
-    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierResolver());
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierProvider());
   }
   /**
    * Mark the written key(s) on the keyed emitter directly — no general-event
@@ -3319,6 +3993,148 @@ var OIMReactiveObject = class extends OIMObject {
   }
 };
 
+// src/core/OIMCollectionStoreTrieDriven.ts
+var OIMCollectionStoreTrieDriven = class extends OIMCollectionStore {
+  constructor() {
+    super(...arguments);
+    this.slots = new OIMTrieMap();
+    this.reservedSlots = new OIMTrieMap();
+  }
+  setOneByPk(pk, entity) {
+    const slot = this.slots.get(pk);
+    if (slot) {
+      slot.item = entity;
+      return slot;
+    }
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = entity;
+      this.reservedSlots.delete(pk);
+      this.slots.set(pk, reserved);
+      return reserved;
+    }
+    const nextSlot = {
+      pk,
+      item: entity
+    };
+    this.slots.set(pk, nextSlot);
+    return nextSlot;
+  }
+  getOrReserveSlotByPk(pk) {
+    const slot = this.slots.get(pk);
+    if (slot) return slot;
+    let reserved = this.reservedSlots.get(pk);
+    if (!reserved) {
+      reserved = { pk, item: void 0 };
+      this.reservedSlots.set(pk, reserved);
+    }
+    return reserved;
+  }
+  setManyByPks(pks, entities) {
+    const slots = [];
+    slots.length = pks.length;
+    for (let i = 0; i < pks.length; i++) {
+      slots[i] = this.setOneByPk(pks[i], entities[i]);
+    }
+    return slots;
+  }
+  getSlotByPk(pk) {
+    return this.slots.get(pk);
+  }
+  findSlotByPk(pk) {
+    return this.slots.get(pk) ?? this.reservedSlots.get(pk);
+  }
+  hasSubscribers(slot) {
+    return slot.subscribers !== void 0 && slot.subscribers.size > 0;
+  }
+  getSlotsByPks(pks) {
+    const result = [];
+    result.length = pks.length;
+    let writeIndex = 0;
+    for (let i = 0; i < pks.length; i++) {
+      const slot = this.slots.get(pks[i]);
+      if (slot !== void 0) result[writeIndex++] = slot;
+    }
+    result.length = writeIndex;
+    return result;
+  }
+  getAllSlots() {
+    return Array.from(this.slots.values());
+  }
+  removeOneByPk(pk) {
+    const slot = this.slots.get(pk);
+    if (slot) {
+      slot.item = void 0;
+      this.slots.delete(pk);
+      if (this.hasSubscribers(slot)) {
+        this.reservedSlots.set(pk, slot);
+      }
+      return;
+    }
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = void 0;
+      if (!this.hasSubscribers(reserved)) {
+        this.reservedSlots.delete(pk);
+      }
+    }
+  }
+  removeManyByPks(pks) {
+    for (const pk of pks) this.removeOneByPk(pk);
+  }
+  getOneByPk(pk) {
+    return this.slots.get(pk)?.item;
+  }
+  getManyByPks(pks) {
+    const result = [];
+    result.length = pks.length;
+    let writeIndex = 0;
+    for (let i = 0; i < pks.length; i++) {
+      const entity = this.getOneByPk(pks[i]);
+      if (entity !== void 0) result[writeIndex++] = entity;
+    }
+    result.length = writeIndex;
+    return result;
+  }
+  getAll() {
+    const result = [];
+    for (const slot of this.slots.values()) {
+      if (slot.item !== void 0) result.push(slot.item);
+    }
+    return result;
+  }
+  countAll() {
+    return this.slots.size;
+  }
+  clear() {
+    const retained = [];
+    for (const slot of this.slots.values()) {
+      slot.item = void 0;
+      if (this.hasSubscribers(slot)) retained.push(slot);
+    }
+    this.slots.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.item = void 0;
+      if (this.hasSubscribers(slot)) retained.push(slot);
+    }
+    this.reservedSlots.clear();
+    for (const slot of retained) {
+      this.reservedSlots.set(slot.pk, slot);
+    }
+  }
+  getAllPks() {
+    return Array.from(this.slots.keys());
+  }
+  destroy() {
+    this.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.subscribers?.clear();
+      slot.subscribers = void 0;
+    }
+    this.reservedSlots.clear();
+  }
+};
+
 // src/core/OIMObjectStoreMapDriven.ts
 var OIMObjectStoreMapDriven = class extends OIMObjectStore {
   constructor() {
@@ -3366,6 +4182,27 @@ var OIMObjectStoreMapDriven = class extends OIMObjectStore {
   }
 };
 
+// src/core/OIMKeyPathCarrierProvider.ts
+var OIMKeyPathCarrierProvider = class {
+  constructor() {
+    this.carriers = new OIMTrieMap();
+  }
+  getOrReserveCarrier(key) {
+    let carrier = this.carriers.get(key);
+    if (!carrier) {
+      carrier = { key };
+      this.carriers.set(key, carrier);
+    }
+    return carrier;
+  }
+  findCarrier(key) {
+    return this.carriers.get(key);
+  }
+  onCarrierEmptied(carrier) {
+    this.carriers.delete(carrier.key);
+  }
+};
+
 // src/core/OIMComparatorFactory.ts
 var OIMComparatorFactory = class {
   createShallowComparator() {
@@ -3584,6 +4421,103 @@ var OIMMap2Keys = class {
   }
 };
 
+// src/core/OIMDisposeScope.ts
+var OIMDisposeScope = class _OIMDisposeScope {
+  constructor() {
+    this.disposables = [];
+    this.disposed = false;
+  }
+  /** Number of not-yet-disposed items currently held. */
+  get size() {
+    return this.disposables.length;
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  /**
+   * Register a disposable (object with `destroy()` or an unsubscribe function)
+   * and return it unchanged, so it can be captured inline. If the scope is
+   * already disposed the item is disposed immediately, so nothing leaks.
+   */
+  add(disposable) {
+    if (this.disposed) {
+      this.disposeOne(disposable);
+      return disposable;
+    }
+    this.disposables.push(disposable);
+    return disposable;
+  }
+  /** A nested scope, itself registered here — dispose it early or with the parent. */
+  child() {
+    return this.add(new _OIMDisposeScope());
+  }
+  /**
+   * Dispose everything in reverse registration order, then clear. Idempotent.
+   * If any `destroy()`/unsubscribe throws, the rest are still disposed and the
+   * first error is rethrown once teardown completes.
+   */
+  destroy() {
+    if (this.disposed) return;
+    this.disposed = true;
+    let firstError;
+    let hasError = false;
+    for (let i = this.disposables.length - 1; i >= 0; i--) {
+      try {
+        this.disposeOne(this.disposables[i]);
+      } catch (error) {
+        if (!hasError) {
+          hasError = true;
+          firstError = error;
+        }
+      }
+    }
+    this.disposables.length = 0;
+    if (hasError) throw firstError;
+  }
+  disposeOne(disposable) {
+    if (typeof disposable === "function") disposable();
+    else disposable.destroy();
+  }
+};
+function createOIMDisposeScope() {
+  return new OIMDisposeScope();
+}
+
+// src/core/OIMTrieSet.ts
+var OIMTrieSet = class {
+  constructor() {
+    this.map = new OIMTrieMap();
+  }
+  get size() {
+    return this.map.size;
+  }
+  add(key) {
+    this.map.set(key, true);
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  delete(key) {
+    return this.map.delete(key);
+  }
+  *values() {
+    yield* this.map.keys();
+  }
+  clear() {
+    this.map.clear();
+  }
+};
+
+// src/core/OIMPkCodecKeyPath.ts
+var OIMPkCodecKeyPath = class {
+  encode(pk) {
+    return JSON.stringify(pk);
+  }
+  decode(encoded) {
+    return JSON.parse(encoded);
+  }
+};
+
 // src/modules/compute/core/OIMComputeRuntime.ts
 var OIMComputeRuntime = class {
   constructor(queue) {
@@ -4187,6 +5121,27 @@ var OIMCollectionSelectors = class {
       key
     );
   }
+  /**
+   * Entities of a composite (key-path) set-based index for one key path, e.g.
+   * `entitiesByCompositeSetIndexKey(index, [projectId, role])`.
+   */
+  entitiesByCompositeSetIndexKey(index, key) {
+    return new OIMEntitiesByIndexKeySetBasedSelector(
+      this.runtime,
+      this.collection,
+      index,
+      key
+    );
+  }
+  /** Entities of a composite (key-path) array-based index for one key path. */
+  entitiesByCompositeArrayIndexKey(index, key) {
+    return new OIMEntitiesByIndexKeyArrayBasedSelector(
+      this.runtime,
+      this.collection,
+      index,
+      key
+    );
+  }
   /** Entities of a keyless (whole-collection) array-based index, ordered. */
   entitiesByArrayGlobalIndex(index) {
     return new OIMEntitiesByGlobalIndexArrayBasedSelector(
@@ -4210,7 +5165,16 @@ function createOIMCollectionKit(queue, opts) {
   const collection = new OIMReactiveCollection(queue, opts);
   const indexFactory = new OIMCollectionIndexFactory(queue, collection);
   const select = new OIMCollectionSelectors(queue, collection);
-  return { queue, collection, indexFactory, select };
+  const scope = new OIMDisposeScope();
+  scope.add(collection);
+  return {
+    queue,
+    collection,
+    indexFactory,
+    select,
+    scope,
+    destroy: () => scope.destroy()
+  };
 }
 
 // src/modules/wrapper/collection/OIMCollectionChangedFields.ts
@@ -5191,35 +6155,20 @@ var OIMComputed = class {
 };
 
 // src/modules/effect/core/OIMEffectDependencyKeyed.ts
-function isReadonlyArray(value) {
-  return Array.isArray(value);
-}
 var OIMEffectDependencyKeyed = class {
-  constructor(source, keyOrKeys) {
+  constructor(source, key) {
     this.source = source;
-    if (isReadonlyArray(keyOrKeys)) {
-      this.keys = keyOrKeys;
-    } else {
-      this.key = keyOrKeys;
-    }
+    this.key = key;
   }
   subscribe(onUpdate) {
-    if (this.keys !== void 0) {
-      return this.source.subscribeOnKeys(this.keys, onUpdate);
-    }
-    if (this.key === void 0) return () => {
-    };
     return this.source.subscribeOnKey(this.key, onUpdate);
   }
 };
 
 // src/modules/effect/core/OIMEffectDependencyKeyedObject.ts
 var OIMEffectDependencyKeyedObject = class {
-  constructor(object, keyOrKeys) {
-    this.dep = new OIMEffectDependencyKeyed(
-      object,
-      keyOrKeys
-    );
+  constructor(object, key) {
+    this.dep = new OIMEffectDependencyKeyed(object, key);
   }
   get source() {
     return this.dep.source;
@@ -5231,11 +6180,8 @@ var OIMEffectDependencyKeyedObject = class {
 
 // src/modules/effect/core/OIMEffectDependencyKeyedCollection.ts
 var OIMEffectDependencyKeyedCollection = class {
-  constructor(collection, pkOrPks) {
-    this.dep = new OIMEffectDependencyKeyed(
-      collection,
-      pkOrPks
-    );
+  constructor(collection, pk) {
+    this.dep = new OIMEffectDependencyKeyed(collection, pk);
   }
   get source() {
     return this.dep.source;
@@ -5247,11 +6193,8 @@ var OIMEffectDependencyKeyedCollection = class {
 
 // src/modules/effect/core/OIMEffectDependencyKeyedIndex.ts
 var OIMEffectDependencyKeyedIndex = class {
-  constructor(index, keyOrKeys) {
-    this.dep = new OIMEffectDependencyKeyed(
-      index,
-      keyOrKeys
-    );
+  constructor(index, key) {
+    this.dep = new OIMEffectDependencyKeyed(index, key);
   }
   get source() {
     return this.dep.source;
@@ -5398,6 +6341,7 @@ export {
   EOIMEventQueueSchedulerEventType,
   EOIMIndexEventType,
   EOIMObjectEventType,
+  OIMBucketCarrierProvider,
   OIMCarrierKeyedEmitter,
   OIMCarrierSingleEmitter,
   OIMCollection,
@@ -5410,6 +6354,7 @@ export {
   OIMCollectionSelectors,
   OIMCollectionStore,
   OIMCollectionStoreMapDriven,
+  OIMCollectionStoreTrieDriven,
   OIMComparatorFactory,
   OIMComputeRuntime,
   OIMComputed,
@@ -5418,6 +6363,7 @@ export {
   OIMDerivedCollectionGlobalIndexSetBased,
   OIMDerivedCollectionIndexArrayBased,
   OIMDerivedCollectionIndexSetBased,
+  OIMDisposeScope,
   OIMEffect,
   OIMEffectDependencyComputed,
   OIMEffectDependencyKeyed,
@@ -5460,6 +6406,11 @@ export {
   OIMIndexStoreMapDrivenArrayBased,
   OIMIndexStoreMapDrivenSetBased,
   OIMIndexStoreSetBased,
+  OIMIndexStoreTrieDrivenArrayBased,
+  OIMIndexStoreTrieDrivenSetBased,
+  OIMKeyPathCarrierProvider,
+  OIMKeyedBucketArrayBased,
+  OIMKeyedBucketSetBased,
   OIMMap2Keys,
   OIMObject,
   OIMObjectStore,
@@ -5471,10 +6422,13 @@ export {
   OIMOrderedListCommandStream,
   OIMOrderedListCommandStreamDiffDriven,
   OIMOrderedListMappedCommandStream,
+  OIMPkCodecKeyPath,
   OIMPkSelectorFactory,
   OIMReactiveCollection,
   OIMReactiveCollectionGlobalIndexManualArrayBased,
   OIMReactiveCollectionGlobalIndexManualSetBased,
+  OIMReactiveCollectionIndexCompositeTrieArrayBased,
+  OIMReactiveCollectionIndexCompositeTrieSetBased,
   OIMReactiveCollectionIndexManualArrayBased,
   OIMReactiveCollectionIndexManualSetBased,
   OIMReactiveGlobalIndex,
@@ -5489,10 +6443,13 @@ export {
   OIMReactiveIndexSetBased,
   OIMReactiveObject,
   OIMSelector,
+  OIMTrieMap,
+  OIMTrieSet,
   createInPlaceEntityUpdater,
   createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit,
+  createOIMDisposeScope,
   createOIMGlobalIndexSlotMap,
   createOIMIndexSlotMap,
   createOIMOrderedListCommandStreamDiffDriven,