@oimdb/core 3.11.0 → 3.12.0

package/README.md

@@ -1331,6 +1331,24 @@ const unsubscribe = users.updateEventEmitter.subscribeOnKey('user1', () => {
 unsubscribe();
 ```
 
+## 🕳️ Missing entities: the holes policy
+
+A pk can point at nothing — never upserted, or removed while an index still holds it. One rule
+applies everywhere:
+
+> **Reads are length-aligned and surface the gap as `undefined`. Dropping it is always a separate,
+> explicitly named call.**
+
+```ts
+collection.getManyByPks(['u1', 'gone', 'u2']);        // [User, undefined, User]
+collection.getManyByPksCompact(['u1', 'gone', 'u2']); // [User, User] — SHORTER, deliberate
+```
+
+`index.getEntitiesByKey`, `globalIndex.getEntities`, `stream.getEntitiesByKey` and every
+list-returning selector follow the same shape. A **derived** index is dense by construction, so the
+`| undefined` there is spurious; a **manual** index (`setPks`, composite) can hold a dangling pk, and
+compacting it away is how a torn state becomes invisible.
+
 ## 📚 API Reference
 
 ### DX Factories

package/dist/index.cjs

@@ -728,19 +728,13 @@ var OIMCarrierKeyedEmitter = class {
     // doubles as membership: a carrier is in this array iff `carrier.dirty`.
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
-    // Number of live subscriptions whose single handler spans 2+ distinct
-    // carriers (a `subscribeOnKeys` over distinct keys). While this is > 0 a
-    // flush coalesces delivery so such a handler fires at most ONCE per flush,
-    // not once per changed carrier — the callback carries no key, so extra
-    // fires are pure waste. At 0 the hot single-subscriber path pays nothing:
-    // no per-flush Set, no membership checks.
-    this.multiCarrierSubscriptions = 0;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
-      const delivered = this.multiCarrierSubscriptions > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
+      const multiCarrierHandlers = this.multiCarrierHandlers;
+      const delivered = multiCarrierHandlers !== void 0 && multiCarrierHandlers.size > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
       let i = 0;
       try {
         for (; i < flushing.length; i++) {
@@ -768,12 +762,14 @@ var OIMCarrierKeyedEmitter = class {
       carriers.push(carrier);
     }
     const spansMultipleCarriers = carriers.length > 1;
-    if (spansMultipleCarriers) this.multiCarrierSubscriptions++;
+    if (spansMultipleCarriers) this.retainMultiCarrierHandler(handler);
     let unsubscribed = false;
     return () => {
       if (unsubscribed) return;
       unsubscribed = true;
-      if (spansMultipleCarriers) this.multiCarrierSubscriptions--;
+      if (spansMultipleCarriers) {
+        this.releaseMultiCarrierHandler(handler);
+      }
       for (let i = 0; i < carriers.length; i++) {
         this.removeHandler(carriers[i], handler);
       }
@@ -784,10 +780,25 @@ var OIMCarrierKeyedEmitter = class {
     if (carrier) this.removeHandler(carrier, handler);
   }
   unsubscribeFromKeys(keys, handler) {
+    if (keys.length > 1) this.releaseMultiCarrierHandler(handler);
     for (let i = 0; i < keys.length; i++) {
       this.unsubscribeFromKey(keys[i], handler);
     }
   }
+  /** Take a reference for a handler whose subscription spans several carriers. */
+  retainMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers ?? (this.multiCarrierHandlers = /* @__PURE__ */ new Map());
+    handlers.set(handler, (handlers.get(handler) ?? 0) + 1);
+  }
+  /** Drop one reference; the handler leaves the set when none are left. */
+  releaseMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers;
+    if (handlers === void 0) return;
+    const count = handlers.get(handler);
+    if (count === void 0) return;
+    if (count > 1) handlers.set(handler, count - 1);
+    else handlers.delete(handler);
+  }
   addHandler(carrier, handler) {
     let subscribers = carrier.subscribers;
     if (!subscribers) {
@@ -876,6 +887,8 @@ var OIMCarrierKeyedEmitter = class {
     }
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
+    this.multiCarrierHandlers?.clear();
+    this.deliveredPool?.clear();
   }
   assertNotInFlush() {
     if (this.queue.isInFlush) {
@@ -892,13 +905,12 @@ var OIMCarrierKeyedEmitter = class {
   notify(carrier, delivered) {
     const subscribers = carrier.subscribers;
     if (!subscribers || subscribers.size === 0) return;
+    const multiCarrierHandlers = delivered ? this.multiCarrierHandlers : void 0;
     if (subscribers.size === 1) {
       const only = subscribers.values().next().value;
       if (!only) return;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(only);
-        if (delivered.size === size) return;
+      if (this.isAlreadyDelivered(only, delivered, multiCarrierHandlers)) {
+        return;
       }
       only();
       return;
@@ -908,14 +920,25 @@ var OIMCarrierKeyedEmitter = class {
     for (let i = 0; i < snapshot.length; i++) {
       const handler = snapshot[i];
       if (!subscribers.has(handler)) continue;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(handler);
-        if (delivered.size === size) continue;
+      if (this.isAlreadyDelivered(handler, delivered, multiCarrierHandlers)) {
+        continue;
       }
       handler();
     }
   }
+  /**
+   * Whether this handler already fired in the current flush and must be
+   * skipped. Only multi-carrier handlers are tracked; everything else always
+   * delivers. Membership is recorded via the size delta of a single `add` —
+   * one hash probe instead of `has` + `add`.
+   */
+  isAlreadyDelivered(handler, delivered, multiCarrierHandlers) {
+    if (delivered === void 0) return false;
+    if (multiCarrierHandlers?.has(handler) !== true) return false;
+    const size = delivered.size;
+    delivered.add(handler);
+    return delivered.size === size;
+  }
 };
 
 // src/core/OIMKeyedCarrierProvider.ts
@@ -1392,6 +1415,13 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
     return this.slots.get(pk)?.item;
   }
   getManyByPks(pks) {
+    const result = new Array(pks.length);
+    for (let i = 0; i < pks.length; i++) {
+      result[i] = this.getOneByPk(pks[i]);
+    }
+    return result;
+  }
+  getManyByPksCompact(pks) {
     const result = [];
     result.length = pks.length;
     let writeIndex = 0;
@@ -1472,9 +1502,14 @@ var OIMCollection = class {
   getOneByPk(pk) {
     return this.store.getOneByPk(pk);
   }
+  /** Length-aligned with `pks`; `undefined` wherever a pk has no entity. */
   getManyByPks(pks) {
     return this.store.getManyByPks(pks);
   }
+  /** Holes filtered out — may be SHORTER than `pks`. Deliberate; see the store's docs. */
+  getManyByPksCompact(pks) {
+    return this.store.getManyByPksCompact(pks);
+  }
   getSlotByPk(pk) {
     return this.store.getSlotByPk(pk);
   }
@@ -4352,6 +4387,13 @@ var OIMCollectionStoreTrieDriven = class extends OIMCollectionStore {
     return this.slots.get(pk)?.item;
   }
   getManyByPks(pks) {
+    const result = new Array(pks.length);
+    for (let i = 0; i < pks.length; i++) {
+      result[i] = this.getOneByPk(pks[i]);
+    }
+    return result;
+  }
+  getManyByPksCompact(pks) {
     const result = [];
     result.length = pks.length;
     let writeIndex = 0;

package/dist/index.d.cts

@@ -62,7 +62,18 @@ declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TO
     abstract removeOneByPk(pk: TPk): void;
     abstract removeManyByPks(pks: readonly TPk[]): void;
     abstract getOneByPk(pk: TPk): TEntity | undefined;
-    abstract getManyByPks(pks: readonly TPk[]): TEntity[];
+    /**
+     * Length-aligned with `pks`: `undefined` wherever a pk has no entity. A missing entity is a real
+     * state of the store, so the read surfaces it instead of deciding for the caller — the same
+     * contract as {@link OIMIndex.getEntitiesByKey} and every selector.
+     */
+    abstract getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    /**
+     * The same read with holes filtered out, so the result may be SHORTER than `pks`. Deliberate and
+     * separately named: silently swallowing a missing entity is exactly what makes torn state hard to
+     * find. Safe when the pks come from a derived index (dense by construction).
+     */
+    abstract getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     abstract getAll(): TEntity[];
     abstract getAllPks(): TPk[];
     abstract countAll(): number;
@@ -509,13 +520,17 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private multiCarrierSubscriptions;
+    private multiCarrierHandlers?;
     private deliveredPool?;
     constructor(queue: OIMEventQueue, carrierProvider: IOIMCarrierProvider<TKey, TCarrier>);
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
     unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
     unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+    /** Take a reference for a handler whose subscription spans several carriers. */
+    private retainMultiCarrierHandler;
+    /** Drop one reference; the handler leaves the set when none are left. */
+    private releaseMultiCarrierHandler;
     private addHandler;
     private removeHandler;
     /** Fast path: the writer already holds the carrier. */
@@ -536,6 +551,13 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private scheduleFlush;
     private readonly onFlush;
     private notify;
+    /**
+     * Whether this handler already fired in the current flush and must be
+     * skipped. Only multi-carrier handlers are tracked; everything else always
+     * delivers. Membership is recorded via the size delta of a single `add` —
+     * one hash probe instead of `has` + `add`.
+     */
+    private isAlreadyDelivered;
 }
 
 /**
@@ -774,7 +796,10 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMKey> {
     protected readonly updateEntity: TOIMEntityUpdater<TEntity>;
     constructor(opts?: TOIMCollectionOptions<TEntity, TPk>);
     getOneByPk(pk: TPk): TEntity | undefined;
-    getManyByPks(pks: readonly TPk[]): TEntity[];
+    /** Length-aligned with `pks`; `undefined` wherever a pk has no entity. */
+    getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    /** Holes filtered out — may be SHORTER than `pks`. Deliberate; see the store's docs. */
+    getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
     getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     /**
@@ -1889,7 +1914,8 @@ declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TO
     removeOneByPk(pk: TPk): void;
     removeManyByPks(pks: readonly TPk[]): void;
     getOneByPk(pk: TPk): TEntity | undefined;
-    getManyByPks(pks: readonly TPk[]): TEntity[];
+    getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     getAll(): TEntity[];
     countAll(): number;
     clear(): void;
@@ -1940,7 +1966,8 @@ declare class OIMCollectionStoreTrieDriven<TEntity extends object> extends OIMCo
     removeOneByPk(pk: TOIMKeyPath): void;
     removeManyByPks(pks: readonly TOIMKeyPath[]): void;
     getOneByPk(pk: TOIMKeyPath): TEntity | undefined;
-    getManyByPks(pks: readonly TOIMKeyPath[]): TEntity[];
+    getManyByPks(pks: readonly TOIMKeyPath[]): (TEntity | undefined)[];
+    getManyByPksCompact(pks: readonly TOIMKeyPath[]): TEntity[];
     getAll(): TEntity[];
     countAll(): number;
     clear(): void;

package/dist/index.d.ts

@@ -62,7 +62,18 @@ declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TO
     abstract removeOneByPk(pk: TPk): void;
     abstract removeManyByPks(pks: readonly TPk[]): void;
     abstract getOneByPk(pk: TPk): TEntity | undefined;
-    abstract getManyByPks(pks: readonly TPk[]): TEntity[];
+    /**
+     * Length-aligned with `pks`: `undefined` wherever a pk has no entity. A missing entity is a real
+     * state of the store, so the read surfaces it instead of deciding for the caller — the same
+     * contract as {@link OIMIndex.getEntitiesByKey} and every selector.
+     */
+    abstract getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    /**
+     * The same read with holes filtered out, so the result may be SHORTER than `pks`. Deliberate and
+     * separately named: silently swallowing a missing entity is exactly what makes torn state hard to
+     * find. Safe when the pks come from a derived index (dense by construction).
+     */
+    abstract getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     abstract getAll(): TEntity[];
     abstract getAllPks(): TPk[];
     abstract countAll(): number;
@@ -509,13 +520,17 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private multiCarrierSubscriptions;
+    private multiCarrierHandlers?;
     private deliveredPool?;
     constructor(queue: OIMEventQueue, carrierProvider: IOIMCarrierProvider<TKey, TCarrier>);
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
     unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
     unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+    /** Take a reference for a handler whose subscription spans several carriers. */
+    private retainMultiCarrierHandler;
+    /** Drop one reference; the handler leaves the set when none are left. */
+    private releaseMultiCarrierHandler;
     private addHandler;
     private removeHandler;
     /** Fast path: the writer already holds the carrier. */
@@ -536,6 +551,13 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private scheduleFlush;
     private readonly onFlush;
     private notify;
+    /**
+     * Whether this handler already fired in the current flush and must be
+     * skipped. Only multi-carrier handlers are tracked; everything else always
+     * delivers. Membership is recorded via the size delta of a single `add` —
+     * one hash probe instead of `has` + `add`.
+     */
+    private isAlreadyDelivered;
 }
 
 /**
@@ -774,7 +796,10 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMKey> {
     protected readonly updateEntity: TOIMEntityUpdater<TEntity>;
     constructor(opts?: TOIMCollectionOptions<TEntity, TPk>);
     getOneByPk(pk: TPk): TEntity | undefined;
-    getManyByPks(pks: readonly TPk[]): TEntity[];
+    /** Length-aligned with `pks`; `undefined` wherever a pk has no entity. */
+    getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    /** Holes filtered out — may be SHORTER than `pks`. Deliberate; see the store's docs. */
+    getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
     getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     /**
@@ -1889,7 +1914,8 @@ declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TO
     removeOneByPk(pk: TPk): void;
     removeManyByPks(pks: readonly TPk[]): void;
     getOneByPk(pk: TPk): TEntity | undefined;
-    getManyByPks(pks: readonly TPk[]): TEntity[];
+    getManyByPks(pks: readonly TPk[]): (TEntity | undefined)[];
+    getManyByPksCompact(pks: readonly TPk[]): TEntity[];
     getAll(): TEntity[];
     countAll(): number;
     clear(): void;
@@ -1940,7 +1966,8 @@ declare class OIMCollectionStoreTrieDriven<TEntity extends object> extends OIMCo
     removeOneByPk(pk: TOIMKeyPath): void;
     removeManyByPks(pks: readonly TOIMKeyPath[]): void;
     getOneByPk(pk: TOIMKeyPath): TEntity | undefined;
-    getManyByPks(pks: readonly TOIMKeyPath[]): TEntity[];
+    getManyByPks(pks: readonly TOIMKeyPath[]): (TEntity | undefined)[];
+    getManyByPksCompact(pks: readonly TOIMKeyPath[]): TEntity[];
     getAll(): TEntity[];
     countAll(): number;
     clear(): void;

package/dist/index.js

@@ -578,19 +578,13 @@ var OIMCarrierKeyedEmitter = class {
     // doubles as membership: a carrier is in this array iff `carrier.dirty`.
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
-    // Number of live subscriptions whose single handler spans 2+ distinct
-    // carriers (a `subscribeOnKeys` over distinct keys). While this is > 0 a
-    // flush coalesces delivery so such a handler fires at most ONCE per flush,
-    // not once per changed carrier — the callback carries no key, so extra
-    // fires are pure waste. At 0 the hot single-subscriber path pays nothing:
-    // no per-flush Set, no membership checks.
-    this.multiCarrierSubscriptions = 0;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
-      const delivered = this.multiCarrierSubscriptions > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
+      const multiCarrierHandlers = this.multiCarrierHandlers;
+      const delivered = multiCarrierHandlers !== void 0 && multiCarrierHandlers.size > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
       let i = 0;
       try {
         for (; i < flushing.length; i++) {
@@ -618,12 +612,14 @@ var OIMCarrierKeyedEmitter = class {
       carriers.push(carrier);
     }
     const spansMultipleCarriers = carriers.length > 1;
-    if (spansMultipleCarriers) this.multiCarrierSubscriptions++;
+    if (spansMultipleCarriers) this.retainMultiCarrierHandler(handler);
     let unsubscribed = false;
     return () => {
       if (unsubscribed) return;
       unsubscribed = true;
-      if (spansMultipleCarriers) this.multiCarrierSubscriptions--;
+      if (spansMultipleCarriers) {
+        this.releaseMultiCarrierHandler(handler);
+      }
       for (let i = 0; i < carriers.length; i++) {
         this.removeHandler(carriers[i], handler);
       }
@@ -634,10 +630,25 @@ var OIMCarrierKeyedEmitter = class {
     if (carrier) this.removeHandler(carrier, handler);
   }
   unsubscribeFromKeys(keys, handler) {
+    if (keys.length > 1) this.releaseMultiCarrierHandler(handler);
     for (let i = 0; i < keys.length; i++) {
       this.unsubscribeFromKey(keys[i], handler);
     }
   }
+  /** Take a reference for a handler whose subscription spans several carriers. */
+  retainMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers ?? (this.multiCarrierHandlers = /* @__PURE__ */ new Map());
+    handlers.set(handler, (handlers.get(handler) ?? 0) + 1);
+  }
+  /** Drop one reference; the handler leaves the set when none are left. */
+  releaseMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers;
+    if (handlers === void 0) return;
+    const count = handlers.get(handler);
+    if (count === void 0) return;
+    if (count > 1) handlers.set(handler, count - 1);
+    else handlers.delete(handler);
+  }
   addHandler(carrier, handler) {
     let subscribers = carrier.subscribers;
     if (!subscribers) {
@@ -726,6 +737,8 @@ var OIMCarrierKeyedEmitter = class {
     }
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
+    this.multiCarrierHandlers?.clear();
+    this.deliveredPool?.clear();
   }
   assertNotInFlush() {
     if (this.queue.isInFlush) {
@@ -742,13 +755,12 @@ var OIMCarrierKeyedEmitter = class {
   notify(carrier, delivered) {
     const subscribers = carrier.subscribers;
     if (!subscribers || subscribers.size === 0) return;
+    const multiCarrierHandlers = delivered ? this.multiCarrierHandlers : void 0;
     if (subscribers.size === 1) {
       const only = subscribers.values().next().value;
       if (!only) return;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(only);
-        if (delivered.size === size) return;
+      if (this.isAlreadyDelivered(only, delivered, multiCarrierHandlers)) {
+        return;
       }
       only();
       return;
@@ -758,14 +770,25 @@ var OIMCarrierKeyedEmitter = class {
     for (let i = 0; i < snapshot.length; i++) {
       const handler = snapshot[i];
       if (!subscribers.has(handler)) continue;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(handler);
-        if (delivered.size === size) continue;
+      if (this.isAlreadyDelivered(handler, delivered, multiCarrierHandlers)) {
+        continue;
       }
       handler();
     }
   }
+  /**
+   * Whether this handler already fired in the current flush and must be
+   * skipped. Only multi-carrier handlers are tracked; everything else always
+   * delivers. Membership is recorded via the size delta of a single `add` —
+   * one hash probe instead of `has` + `add`.
+   */
+  isAlreadyDelivered(handler, delivered, multiCarrierHandlers) {
+    if (delivered === void 0) return false;
+    if (multiCarrierHandlers?.has(handler) !== true) return false;
+    const size = delivered.size;
+    delivered.add(handler);
+    return delivered.size === size;
+  }
 };
 
 // src/core/OIMKeyedCarrierProvider.ts
@@ -1242,6 +1265,13 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
     return this.slots.get(pk)?.item;
   }
   getManyByPks(pks) {
+    const result = new Array(pks.length);
+    for (let i = 0; i < pks.length; i++) {
+      result[i] = this.getOneByPk(pks[i]);
+    }
+    return result;
+  }
+  getManyByPksCompact(pks) {
     const result = [];
     result.length = pks.length;
     let writeIndex = 0;
@@ -1322,9 +1352,14 @@ var OIMCollection = class {
   getOneByPk(pk) {
     return this.store.getOneByPk(pk);
   }
+  /** Length-aligned with `pks`; `undefined` wherever a pk has no entity. */
   getManyByPks(pks) {
     return this.store.getManyByPks(pks);
   }
+  /** Holes filtered out — may be SHORTER than `pks`. Deliberate; see the store's docs. */
+  getManyByPksCompact(pks) {
+    return this.store.getManyByPksCompact(pks);
+  }
   getSlotByPk(pk) {
     return this.store.getSlotByPk(pk);
   }
@@ -4202,6 +4237,13 @@ var OIMCollectionStoreTrieDriven = class extends OIMCollectionStore {
     return this.slots.get(pk)?.item;
   }
   getManyByPks(pks) {
+    const result = new Array(pks.length);
+    for (let i = 0; i < pks.length; i++) {
+      result[i] = this.getOneByPk(pks[i]);
+    }
+    return result;
+  }
+  getManyByPksCompact(pks) {
     const result = [];
     result.length = pks.length;
     let writeIndex = 0;

package/llms.txt

@@ -86,7 +86,9 @@ byRole.subscribeOnKey('admin', () => {
 queue.flush(); // delivers subscription
 ```
 
-**`subscribeOnKeys(keys, handler)` delivery is coalesced per flush:** the handler fires at most ONCE per flush no matter how many of the subscribed keys changed in it (the callback gets no key, so per-key fan-out would be pure waste). This holds across all reactive primitives — sync (collection / index / object, via `OIMCarrierKeyedEmitter`) and the `@oimdb/async` nodes (via `OIMUpdateEventEmitterAsync`) alike. `subscribeOnKey` (single key) is unchanged. Handler identity is preserved, so `unsubscribeFromKeys(keys, handler)` still removes a `subscribeOnKeys` subscription.
+**`subscribeOnKeys(keys, handler)` delivery is coalesced per flush:** the handler fires at most ONCE per flush no matter how many of the subscribed keys changed in it (the callback gets no key, so per-key fan-out would be pure waste). This holds across all reactive primitives — sync (collection / index / object, via `OIMCarrierKeyedEmitter`) and the `@oimdb/async` nodes (via `OIMUpdateEventEmitterAsync`) alike. `subscribeOnKey` (single key) is unchanged. Handler identity is preserved, so `unsubscribeFromKeys(keys, handler)` still removes a `subscribeOnKeys` subscription — and releases the coalescing exactly like the returned unsubscribe closure does.
+
+**Coalescing is scoped to the subscription, not to the handler.** It applies only to handlers registered through a multi-key `subscribeOnKeys`. If the same function holds several *independent* `subscribeOnKey` subscriptions, it still gets one delivery per changed key — an unrelated multi-key subscription elsewhere on the same collection/index never changes that.
 
 Membership writes are incremental (touch only the changed pks):
 - `addPks(key, pks)` / `removePks(key, pks)` — **set-based**: O(1) per pk for both. **array-based**: `addPks` O(1), `removePks` O(bucket) (ordered, must scan).
@@ -393,41 +395,55 @@ Signal hooks: `useSelectEntityByPkSignal(collection, pk)`, `useSelectPksByIndexK
 
 Trade-offs (use only when every reader is subscription-driven): NOT Concurrent-safe; the entity reference is stable across changes, so `React.memo` on entities, prev/next diffing, time-travel, and the default uSES hooks on the same collection won't see updates. Default to the standard immutable hooks; reach for this only when a profile shows the data layer is the bottleneck.
 
+### Missing entities: the holes policy
+
+A pk can point at nothing (never upserted, or removed while an index still holds it). ONE rule across the library: **reads are length-aligned and surface the gap as `undefined`; dropping it is always a separate, explicitly named call.** `collection.getManyByPks(pks)` → `(TEntity | undefined)[]`, aligned. `collection.getManyByPksCompact(pks)` → `TEntity[]`, filtered and possibly SHORTER. Same shape for `index.getEntitiesByKey`, `globalIndex.getEntities`, `stream.getEntitiesByKey` and every list-returning selector. A DERIVED index is dense by construction, so there the `| undefined` is spurious — but a MANUAL index (`setPks`, composite) can genuinely hold a dangling pk, and compacting it away is how torn state becomes invisible. `@oimdb/exodra` mirrors this: default index read keeps holes, `.compact(key)` filters, `.unsafeDense(key)` only retypes and checks nothing.
+
 ## Exodra (`@oimdb/exodra`)
 
 ```bash
 npm install @oimdb/exodra @oimdb/core
 ```
 
-Depends only on the type-only `@exodra/reactivity-types` (never the reactivity runtime); peer dep `@oimdb/core`. Your Exodra app already provides `@exodra/reactivity` for the runtime (`bindable`, `derive`, `h`). The [Exodra](https://exodra.org) counterpart of `@oimdb/react`: instead of a hook + re-render, every OIMDB source becomes a read-only Exodra bindable (`TExoBindable<T> = { getValue(): T; subscribe(update): () => void }`). No React. Built on `@oimdb/core`'s `OIMSelector` (`{ getValue, watch }`) — the fine-grained subscription already lives there, so this is a thin adapter. Bindables are read-only, lazy (subscribe upstream only while they have a downstream subscriber → cost O(visible)) and SSR-safe (`getValue()` reads fresh, valid without an active subscription).
+The Exodra counterpart of `@oimdb/react`: instead of a hook + re-render, every OIMDB read becomes a read-only Exodra bindable (`TExoBindable<T> = { getValue(): T; subscribe(update): () => void }`). No React. Built on `@oimdb/core`'s `OIMSelector` (`{ getValue, watch }`) — the fine-grained subscription already lives there, so this is a thin adapter. Depends only on the type-only `@exodra/reactivity-types` (never the reactivity runtime); peer dep `@oimdb/core`. Everything produced is read-only, lazy + ref-counted (upstream subscribed only while a downstream subscriber exists → O(visible)) and SSR-safe (`getValue()` reads through, valid with no subscription — a reactive key resolves on every read, never stale).
 
 ```ts
-import { fromSelector, bindSelectors, fromComputed, combine, entityRows } from '@oimdb/exodra';
-import { bindable, derive } from '@exodra/reactivity';
+import { exoDb } from '@oimdb/exodra';
+import { bindable, derive, h } from '@exodra/reactivity';
+
+const byTeam        = usersKit.indexFactory.derivedSetIndex<string>(u => u.teamId);
+const byTeamOrdered = usersKit.indexFactory.derivedArrayIndex<string>(u => u.teamId, { orderBy: u => u.name });
+const online        = usersKit.indexFactory.derivedSetGlobalIndex({ filter: u => u.online });
 
-// wrap any OIMSelector
-const alice = fromSelector(kit.select.byPk('u1')); // TExoBindable<User | undefined>
+const db = exoDb({
+    users: { kit: usersKit, indexes: { byTeam, byTeamOrdered, online } },
+    tags:  { kit: tagsKit },                                 // no indexes → byPk / byPks only
+});
 
-// mirror OIMCollectionSelectors → bindables; keys accept a bindable (reactive key re-points the sub)
-const bound = bindSelectors(kit.select);
-const selectedTeam = bindable('team-1');
-const members = bound.entitiesBySetIndexKey(usersByTeam, selectedTeam);
-// <ul bindable={{ children: entityRows(memberPks, pk => bound.byPk(pk), (u, pk) => renderRow(u)) }} />
+const team = bindable('t1');
+db.users.byPk('u1');                            // TExoBindable<User | undefined>
+db.users.byTeam(team);                          // set index — the kind is inferred from the index
+db.users.online();                              // global index — no key, and none is asked for
+db.users.byTeamOrdered.rows(team, render);      // → bindables.children      (identity-stable)
+db.users.byTeamOrdered.list('t1', render);      // → bindableLists.children  (O(delta), fixed key)
 ```
 
 | Export | Purpose |
 |---|---|
-| `fromSelector(selector, opts?)` | primary adapter: `OIMSelector<T>` → `TExoBindable<T>` |
-| `fromOimdb(read, subscribe, opts?)` | escape hatch for a raw read/subscribe pair |
-| `fromSelectorFactory(key, makeSelector, opts?)` | reactive key (`TKey \| bindable`) → rebuilds the selector on change |
-| `fromComputed(computed, opts?)` | `OIMComputed<T>` → `TExoBindable<T>` |
-| `combine(sources, fn)` | multi-source derive (Exodra's own `derive` is single-source) |
-| `bindSelectors(selectors, defaults?)` | mirror of `OIMCollectionSelectors`, each method returning a bindable |
-| `keyedChildren(source, { key, render })` / `entityRows(order, bindEntity, render)` | identity-stable list children (field edit = reconcile no-op, focus-safe) |
-| `listFromCommandStream(stream, key, render)` | O(delta) path: OIMDB ordered command stream → Exodra `bindableList` (commands map 1:1 to `TExoListOp`) |
-| `read*/subscribe*` (6 fns) | low-level pairs mirroring an inline app bridge 1:1 (find-replace migration) |
-
-Options `{ equals?, alwaysNotify? }`: `equals` defaults to `Object.is`; `alwaysNotify: true` for in-place entity updaters (stable ref, where `Object.is` would swallow the update). `bindSelectors` takes `kit.select` (not a bare collection) because the collection's queue is private and the selectors own a queue-bound compute runtime. Exodra bucket bindings subscribe at *build* (not `onExoMount`); the low-level `subscribe*` fns cover `onExoMount`-scoped needs. Write-side is intentionally omitted (apps write via orchestration, e.g. cnstra, not from views).
+| `exoDb(spec)` | whole system at once: `{ name: { kit, indexes? } }` → record of typed views |
+| `exoCollection(kit, indexes?)` | one collection's Exodra view; `kit` stays reachable for writes |
+| `<collection>.all()` | every entity, reactively — non-stale `<option>` lists, and the change signal for `exoCombine` when a row key depends on another collection |
+| `exoSource(read, subscribe)` | base primitive: a raw pair → a lazy, ref-counted bindable |
+| `exoSelector(selector)` / `exoComputed(computed)` | an `OIMSelector` / `OIMComputed` → a bindable |
+| `exoKeyed(keyBindable, makeSelector)` | a MOVING key: repoints the selector as the key changes |
+| `exoCombine(sources, fn)` | multi-source derive (Exodra's own `derive` is single-source) |
+| `exoChildren(source, { key, render })` | identity-stable children for any items |
+| `exoList(stream, key, render)` | OIMDB ordered command stream → Exodra `bindableList` (commands map 1:1 to `TExoListOp`) |
+
+Each named index becomes a CALLABLE member of that name carrying `pks`, `rows`, `subscribe` (and `list` on ordered ones), so the caller never picks a method to match the index kind and never passes the index object again. Any key accepts `TKey | TOIMExodraReadable<TKey>`. Dispatch is structural: array-based `getPksByKey` returns `TPk[]`, set-based returns `Set<TPk>`, keyless ones have none; composite indexes are the same classes with an array key, resolved per call via `Array.isArray(key)`. **`list` exists only on array-based indexes** — a stream is derived by diffing an order and a set has none; enforced in the types, and it builds/memoizes the stream itself. `indexes` is a second argument because a kit does not own its indexes (`kit.indexFactory` creates them, the app keeps them); if core ever lets a kit hold named indexes this becomes optional without a break.
+
+**No function in this package takes an equality option, and there is no options type.** Equality belongs to whoever owns the value: `OIMSelector.areEqual` for selectors (override it), `OIMComputed`'s `compare` for computeds (pass at construction), your own `fn` for `exoCombine` (return a stable reference when content is unchanged), your own `subscribe` callback for `exoSource(read, subscribe)` (compare there and don't call `onChange` — that callback IS the extension point). Those owners run BELOW the bridge, so a filter here could only reject what they passed, never resurrect what they dropped; in-place entity updaters need no configuration anywhere. `exoCombine` drops recomputes landing on the same value, collapsing the N notifications N sources produce for one logical change — not glitch-free though, so put real fan-in in ONE `OIMComputed` forwarded via `exoComputed`. `exoChildren` reads are idempotent (same array reference back, no render, no eviction, until the key sequence changes) and require UNIQUE keys — a duplicate throws rather than placing one schema object twice. `exoList` memoizes `render` per item, so repeated `snapshot()` calls return the same row objects (identity is what Exodra reconciles on); the memo is pruned against the live order on snapshot and amortized past 2x the live row count. Reads are length-aligned WITH HOLES by default (`readonly (T | undefined)[]`, matching `@oimdb/react`) — a missing entity is a real state of the store and hiding it is not the bridge's call. Dropping holes is explicit and never a flag: `<index>.compact(key)` filters (may be SHORTER — on MANUAL `setPks` pks that silently swallows a torn state), `<index>.unsafeDense(key)` filters and checks NOTHING and just retypes to `readonly T[]` — correct for a DERIVED index, which is dense by construction, and `unsafe` because the guarantee is the caller's. Pure aliases of a single core call (`getOneByPk`, `subscribeOnKey`, `getPksByKey`) are NOT exported — call core directly. Pair `exoDb` with Exodra's own DI: `createContextKey<typeof db>('db')`, created by the app since this package pulls types only. Exodra bucket bindings subscribe at *build* (not `onExoMount`); `<index>.subscribe(key, onChange)` covers `onExoMount`-scoped needs. No function takes more than one shape of argument: a fixed key and a moving key are different members (`<index>(key)` vs `<index>.for(keyBindable)`), never one member that inspects what it was given. `exoCombine`'s FIRST emit after subscribing always propagates — OIMDB sources fire synchronously on subscribe and a binding is built from `getValue()` then wired a moment later, so suppressing it leaves the region frozen at its build-time value. Sorting and filtering belong in the index (`derivedArrayIndex({ orderBy })`, or emit no key for excluded entities), not in `rows` — there they are maintained incrementally instead of recomputed per read. The PRIMITIVES are the load-bearing API: screens that sort/filter beyond an index, key rows off related data, or fan in across collections are built from `exoChildren` over an `OIMComputed` forwarded by `exoComputed`, and that is the intended path, not a fallback. Patterns: ordered column → order in the index (`derivedArrayIndex({ orderBy })`), never a per-render sort; filtered list → emit no key for excluded entities; a row that follows another collection → bind INSIDE the row (`derive(exoSelector(other.select.byPk(id)), …)`) so only that node updates; a row KEY derived from another collection → `exoChildren(exoCombine([a.all(), b.all()], read), { key, render })`; `<select>` options → `all()`, never a one-off `getAll()` at build; aggregate → ONE `OIMComputed` + `exoComputed`; moving selection → `<index>.for(keyBindable)`; `onExoMount` scope → `<index>.subscribe(key, onChange)`. Write-side is intentionally omitted (apps write via orchestration, e.g. cnstra, not from views).
+
 
 ## Persist (`@oimdb/persist`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/core",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",