@oimdb/core 3.7.0 → 3.8.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,22 +533,18 @@ 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)
+    );
   }
 };
 
@@ -507,11 +633,19 @@ var OIMCarrierKeyedEmitter = class {
     this.scheduleFlush();
   }
   markUpdatedKey(key) {
+    if (this.subscribedCarriers.size === 0) {
+      this.assertNotInFlush();
+      return;
+    }
     const carrier = this.resolver.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() {
@@ -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, createResolver = () => new OIMKeyedCarrierResolver()) {
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, createResolver());
     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, createResolver) {
+    super(queue, createIndex, createResolver);
   }
   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, createResolver) {
+    super(queue, createIndex, createResolver);
   }
   getPksByKey(key) {
     return this.index.getPksByKey(key);
@@ -963,10 +1097,24 @@ var OIMPkSelectorFactory = class {
   }
 };
 
+// src/core/OIMKeyDomainNative.ts
+var OIMKeyDomainNative = class {
+  createMap() {
+    return /* @__PURE__ */ new Map();
+  }
+  createSet() {
+    return /* @__PURE__ */ new Set();
+  }
+  canonicalize(key) {
+    return key;
+  }
+};
+
 // src/core/OIMCollectionStoreMapDriven.ts
 var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   constructor() {
     super(...arguments);
+    this.keyDomain = new OIMKeyDomainNative();
     this.slots = /* @__PURE__ */ new Map();
     // Slots reserved by indexes for PKs whose entity has not arrived yet.
     // They carry `item: undefined` and live apart from `slots` so they do not
@@ -1139,6 +1287,10 @@ var OIMCollection = class {
     this.store = opts?.store ?? new OIMCollectionStoreMapDriven();
     this.updateEntity = opts?.updateEntity ?? new OIMEntityUpdaterFactory().createMergeEntityUpdater();
   }
+  /** The collection's PK keying strategy — read by indexes and wrappers. */
+  get keyDomain() {
+    return this.store.keyDomain;
+  }
   getOneByPk(pk) {
     return this.store.getOneByPk(pk);
   }
@@ -1219,15 +1371,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 +1389,13 @@ var OIMReactiveCollection = class extends OIMCollection {
   constructor(queue, opts) {
     super(opts);
     this.anyUpdateHandlers = /* @__PURE__ */ new Set();
-    this.pendingAnyUpdatePks = /* @__PURE__ */ new Set();
+    this.pendingAnyUpdatePks = this.store.keyDomain.createSet();
     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 +1554,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 +1596,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,36 +1632,33 @@ 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
@@ -2030,43 +2176,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/OIMBucketCarrierResolver.ts
+var OIMBucketCarrierResolver = 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 +2246,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 +2259,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 OIMBucketCarrierResolver(store)
+    );
   }
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
@@ -2106,6 +2284,7 @@ var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased
 var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexManualArrayBased {
   constructor(queue, opts) {
     const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    const pkDomain = opts.collection?.keyDomain ?? new OIMKeyDomainNative();
     super(queue, {
       indexOptions: opts.indexOptions
     });
@@ -2113,9 +2292,10 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
     // a Set from the whole bucket on every call). Kept in sync by setSlots/clear.
     this.pksByKey = /* @__PURE__ */ new Map();
     this.resolveSlot = resolveSlot;
+    this.pkDomain = pkDomain;
   }
   setPks(key, pks) {
-    const pkSet = /* @__PURE__ */ new Set();
+    const pkSet = this.pkDomain.createSet();
     for (let i = 0; i < pks.length; i++) pkSet.add(pks[i]);
     this.pksByKey.set(key, pkSet);
     super.setSlots(key, this.resolveSlots(pks));
@@ -2158,7 +2338,7 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
   membershipOf(key) {
     let pkSet = this.pksByKey.get(key);
     if (!pkSet) {
-      pkSet = /* @__PURE__ */ new Set();
+      pkSet = this.pkDomain.createSet();
       const existing = this.index.getSlotsByKey(key);
       for (let i = 0; i < existing.length; i++) {
         pkSet.add(existing[i].pk);
@@ -2192,24 +2372,98 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
 var OIMIndexManualSetBased = class extends OIMIndexSetBased {
   constructor(options = {}) {
     super(options);
+    this.pkDomain = options.pkDomain ?? new OIMKeyDomainNative();
   }
   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, resolveSlot) {
+    const bucket = this.setStore.getOrReserveBucket(key);
+    const slots = [];
+    for (let i = 0; i < pks.length; i++) slots.push(resolveSlot(pks[i]));
+    this.replaceBucketContents(bucket, slots);
+    const membership = bucket.membership ?? (bucket.membership = this.pkDomain.createMap());
+    membership.clear();
+    for (let i = 0; i < pks.length; i++) {
+      if (!membership.has(pks[i])) membership.set(pks[i], slots[i]);
+    }
+  }
+  addPks(key, pks, resolveSlot) {
+    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 pk = pks[i];
+      if (membership.has(pk)) continue;
+      const slot = resolveSlot(pk);
+      membership.set(pk, slot);
+      if (!bucket.has(slot)) {
+        bucket.add(slot);
+        changed = true;
+      }
+    }
+    if (!changed) return;
+    this.setStore.retainBucket(bucket);
+    this.emitBucketChanged(bucket);
+  }
+  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 = this.pkDomain.createMap();
+      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 (no copy of the existing Set) and
-   * emits once. O(added). Used by collection-bound indexes for fast `addPks`.
+   * 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 +2471,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 +2501,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 +2525,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 +2540,16 @@ 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,
+        pkDomain: opts?.pkDomain
+      }),
+      () => new OIMBucketCarrierResolver(store)
+    );
   }
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
@@ -2294,71 +2570,26 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   constructor(queue, opts) {
     const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
     super(queue, {
-      indexOptions: opts.indexOptions
+      indexOptions: opts.indexOptions,
+      pkDomain: opts.collection?.keyDomain
     });
-    // 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();
+    // Bound once so the hot pk-write path passes a stable function (no per-call
+    // closure allocation).
+    this.resolveRequiredSlot = (pk) => {
+      const slot = this.resolveSlot(pk);
+      if (!slot) return { pk, item: void 0 };
+      return slot;
+    };
     this.resolveSlot = resolveSlot;
   }
   setPks(key, pks) {
-    const map = /* @__PURE__ */ new Map();
-    const slots = [];
-    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);
-    }
-    this.slotByPk.set(key, map);
-    super.setSlots(key, slots);
+    this.index.setPks(key, pks, this.resolveRequiredSlot);
   }
   addPks(key, pks) {
-    if (pks.length === 0) return;
-    const map = 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 (newSlots.length > 0) this.addSlots(key, newSlots);
+    this.index.addPks(key, pks, this.resolveRequiredSlot);
   }
   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);
-      }
-    }
-    if (removed.length === 0) return;
-    if (map.size === 0) this.slotByPk.delete(key);
-    this.removeSlots(key, removed);
-  }
-  clear(key) {
-    if (key === void 0) this.slotByPk.clear();
-    else this.slotByPk.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.
-   */
-  membershipOf(key) {
-    let map = this.slotByPk.get(key);
-    if (!map) {
-      map = /* @__PURE__ */ new Map();
-      const existing = this.index.getSlotsByKey(key);
-      for (const slot of existing) map.set(slot.pk, slot);
-      this.slotByPk.set(key, map);
-    }
-    return map;
+    this.index.removePks(key, pks);
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -2366,50 +2597,459 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   getEntitiesByKeys(keys) {
     return super.getEntitiesByKeys(keys);
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
-    if (!slot) return { pk, item: void 0 };
-    return slot;
-  }
 };
 
-// src/core/OIMDerivedCollectionIndexSetBased.ts
-var OIMDerivedCollectionIndexSetBased = class extends OIMReactiveCollectionIndexManualSetBased {
-  constructor(queue, collection, opts) {
-    super(queue, {
-      collection,
-      indexOptions: opts.indexOptions
-    });
-    this.keysByPk = /* @__PURE__ */ new Map();
-    this.onCollectionUpdate = (pks) => {
-      if (pks.length === 0) {
-        this.rebuildFromCollection();
-        return;
+// 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;
       }
-      for (const pk of pks) {
-        this.syncPk(pk);
+      let next = children.get(path[i]);
+      if (!next) {
+        next = { hasValue: false };
+        children.set(path[i], next);
       }
-    };
-    this.collection = collection;
-    this.selectIndexKeys = opts.selectIndexKeys;
-    this.unsubscribeFromCollection = collection.emitter.on(
-      0 /* UPDATE */,
-      (payload) => this.onCollectionUpdate(payload.pks)
-    );
-    if (opts.buildInitial !== false) {
-      this.rebuildFromCollection();
+      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;
   }
-  rebuildFromCollection() {
-    this.keysByPk.clear();
-    super.clear();
-    const slotsByKey = /* @__PURE__ */ new Map();
-    const slots = this.collection.getAllSlots();
-    for (const slot of slots) {
-      if (slot.item === void 0) continue;
-      const keys = this.normalizeKeys(this.selectIndexKeys(slot.item));
-      if (keys.length === 0) continue;
-      this.keysByPk.set(slot.pk, new Set(keys));
+  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 resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    super(queue, {
+      indexOptions: {
+        comparePks: opts.indexOptions?.comparePks,
+        store: opts.indexOptions?.store ?? new OIMIndexStoreTrieDrivenSetBased()
+      },
+      pkDomain: opts.collection?.keyDomain
+    });
+    this.resolveRequiredSlot = (pk) => {
+      const slot = this.resolveSlot(pk);
+      if (!slot) return { pk, item: void 0 };
+      return slot;
+    };
+    this.resolveSlot = resolveSlot;
+  }
+  setPks(key, pks) {
+    this.index.setPks(key, pks, this.resolveRequiredSlot);
+  }
+  addPks(key, pks) {
+    this.index.addPks(key, pks, this.resolveRequiredSlot);
+  }
+  removePks(key, pks) {
+    this.index.removePks(key, pks);
+  }
+  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 resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
+    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.resolveSlot = resolveSlot;
+  }
+  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));
+  }
+  addPks(key, pks) {
+    if (pks.length === 0) return;
+    const pkSet = this.membershipOf(key);
+    const newSlots = [];
+    for (const pk of pks) {
+      if (pkSet.has(pk)) continue;
+      pkSet.add(pk);
+      newSlots.push(this.resolveRequiredSlot(pk));
+    }
+    if (newSlots.length > 0) this.appendSlots(key, newSlots);
+  }
+  removePks(key, pks) {
+    if (pks.length === 0) return;
+    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 (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);
+    super.clear(key);
+  }
+  /**
+   * 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 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);
+    }
+    return pkSet;
+  }
+  getEntitiesByKey(key) {
+    return super.getEntitiesByKey(key);
+  }
+  getEntitiesByKeys(keys) {
+    return super.getEntitiesByKeys(keys);
+  }
+  resolveSlots(pks) {
+    const slots = [];
+    slots.length = pks.length;
+    for (let i = 0; i < pks.length; i++) {
+      slots[i] = this.resolveRequiredSlot(pks[i]);
+    }
+    return slots;
+  }
+  resolveRequiredSlot(pk) {
+    const slot = this.resolveSlot(pk);
+    if (!slot) return { pk, item: void 0 };
+    return slot;
+  }
+};
+
+// src/core/OIMDerivedCollectionIndexSetBased.ts
+var OIMDerivedCollectionIndexSetBased = class extends OIMReactiveCollectionIndexManualSetBased {
+  constructor(queue, collection, opts) {
+    super(queue, {
+      collection,
+      indexOptions: opts.indexOptions
+    });
+    this.keysByPk = /* @__PURE__ */ new Map();
+    this.onCollectionUpdate = (pks) => {
+      if (pks.length === 0) {
+        this.rebuildFromCollection();
+        return;
+      }
+      for (const pk of pks) {
+        this.syncPk(pk);
+      }
+    };
+    this.collection = collection;
+    this.selectIndexKeys = opts.selectIndexKeys;
+    this.unsubscribeFromCollection = collection.emitter.on(
+      0 /* UPDATE */,
+      (payload) => this.onCollectionUpdate(payload.pks)
+    );
+    if (opts.buildInitial !== false) {
+      this.rebuildFromCollection();
+    }
+  }
+  rebuildFromCollection() {
+    this.keysByPk.clear();
+    super.clear();
+    const slotsByKey = /* @__PURE__ */ new Map();
+    const slots = this.collection.getAllSlots();
+    for (const slot of slots) {
+      if (slot.item === void 0) continue;
+      const keys = this.normalizeKeys(this.selectIndexKeys(slot.item));
+      if (keys.length === 0) continue;
+      this.keysByPk.set(slot.pk, new Set(keys));
       for (const key of keys) {
         let slotsForKey = slotsByKey.get(key);
         if (!slotsForKey) {
@@ -3071,6 +3711,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,
@@ -3319,6 +3983,195 @@ var OIMReactiveObject = class extends OIMObject {
   }
 };
 
+// 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/OIMKeyDomainTrie.ts
+var OIMKeyDomainTrie = class {
+  constructor() {
+    // Interning pool: logical key (by content) → the one canonical reference.
+    this.pool = new OIMTrieMap();
+  }
+  createMap() {
+    return new OIMTrieMap();
+  }
+  createSet() {
+    return new OIMTrieSet();
+  }
+  canonicalize(key) {
+    const existing = this.pool.get(key);
+    if (existing !== void 0) return existing;
+    const canonical = Object.freeze(key.slice());
+    this.pool.set(canonical, canonical);
+    return canonical;
+  }
+};
+
+// src/core/OIMCollectionStoreTrieDriven.ts
+var OIMCollectionStoreTrieDriven = class extends OIMCollectionStore {
+  constructor(keyDomain = new OIMKeyDomainTrie()) {
+    super();
+    this.keyDomain = keyDomain;
+    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: this.keyDomain.canonicalize(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: this.keyDomain.canonicalize(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 +4219,27 @@ var OIMObjectStoreMapDriven = class extends OIMObjectStore {
   }
 };
 
+// src/core/OIMKeyPathCarrierResolver.ts
+var OIMKeyPathCarrierResolver = 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 +4458,78 @@ 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/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 +5133,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 +5177,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
@@ -5398,6 +6374,7 @@ export {
   EOIMEventQueueSchedulerEventType,
   EOIMIndexEventType,
   EOIMObjectEventType,
+  OIMBucketCarrierResolver,
   OIMCarrierKeyedEmitter,
   OIMCarrierSingleEmitter,
   OIMCollection,
@@ -5410,6 +6387,7 @@ export {
   OIMCollectionSelectors,
   OIMCollectionStore,
   OIMCollectionStoreMapDriven,
+  OIMCollectionStoreTrieDriven,
   OIMComparatorFactory,
   OIMComputeRuntime,
   OIMComputed,
@@ -5418,6 +6396,7 @@ export {
   OIMDerivedCollectionGlobalIndexSetBased,
   OIMDerivedCollectionIndexArrayBased,
   OIMDerivedCollectionIndexSetBased,
+  OIMDisposeScope,
   OIMEffect,
   OIMEffectDependencyComputed,
   OIMEffectDependencyKeyed,
@@ -5460,6 +6439,13 @@ export {
   OIMIndexStoreMapDrivenArrayBased,
   OIMIndexStoreMapDrivenSetBased,
   OIMIndexStoreSetBased,
+  OIMIndexStoreTrieDrivenArrayBased,
+  OIMIndexStoreTrieDrivenSetBased,
+  OIMKeyDomainNative,
+  OIMKeyDomainTrie,
+  OIMKeyPathCarrierResolver,
+  OIMKeyedBucketArrayBased,
+  OIMKeyedBucketSetBased,
   OIMMap2Keys,
   OIMObject,
   OIMObjectStore,
@@ -5471,10 +6457,13 @@ export {
   OIMOrderedListCommandStream,
   OIMOrderedListCommandStreamDiffDriven,
   OIMOrderedListMappedCommandStream,
+  OIMPkCodecKeyPath,
   OIMPkSelectorFactory,
   OIMReactiveCollection,
   OIMReactiveCollectionGlobalIndexManualArrayBased,
   OIMReactiveCollectionGlobalIndexManualSetBased,
+  OIMReactiveCollectionIndexCompositeTrieArrayBased,
+  OIMReactiveCollectionIndexCompositeTrieSetBased,
   OIMReactiveCollectionIndexManualArrayBased,
   OIMReactiveCollectionIndexManualSetBased,
   OIMReactiveGlobalIndex,
@@ -5489,10 +6478,13 @@ export {
   OIMReactiveIndexSetBased,
   OIMReactiveObject,
   OIMSelector,
+  OIMTrieMap,
+  OIMTrieSet,
   createInPlaceEntityUpdater,
   createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit,
+  createOIMDisposeScope,
   createOIMGlobalIndexSlotMap,
   createOIMIndexSlotMap,
   createOIMOrderedListCommandStreamDiffDriven,