@oimdb/core 3.11.1 → 3.12.1

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

@@ -1415,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;
@@ -1495,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);
   }
@@ -4375,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;
@@ -785,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>;
     /**
@@ -1796,7 +1810,12 @@ type TOIMDerivedCollectionOptions<TDerived extends object, TPk extends TOIMKey>
  * listens to the source and keeps itself in sync — add / update / remove.
  *
  * It is a first-class `OIMReactiveCollection`, so it can be indexed, selected,
- * and derived-from again (join → join). Maintenance runs on the source's
+ * and derived-from again — a CHAIN of one-to-one projections, not a join. There
+ * is deliberately no multi-source variant: a joined row would need a primary key
+ * nobody references, and an identity nobody uses is not an identity. Combine
+ * across collections with one `OIMComputed`, or, if something really does
+ * reference the combined thing, give it its own collection and write to it.
+ * Maintenance runs on the source's
  * synchronous UPDATE channel, so a chain of derivations stays consistent within
  * the same flush; delivery to keyed subscribers is batched on flush as usual.
  *
@@ -1900,7 +1919,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;
@@ -1951,7 +1971,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;
@@ -785,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>;
     /**
@@ -1796,7 +1810,12 @@ type TOIMDerivedCollectionOptions<TDerived extends object, TPk extends TOIMKey>
  * listens to the source and keeps itself in sync — add / update / remove.
  *
  * It is a first-class `OIMReactiveCollection`, so it can be indexed, selected,
- * and derived-from again (join → join). Maintenance runs on the source's
+ * and derived-from again — a CHAIN of one-to-one projections, not a join. There
+ * is deliberately no multi-source variant: a joined row would need a primary key
+ * nobody references, and an identity nobody uses is not an identity. Combine
+ * across collections with one `OIMComputed`, or, if something really does
+ * reference the combined thing, give it its own collection and write to it.
+ * Maintenance runs on the source's
  * synchronous UPDATE channel, so a chain of derivations stays consistent within
  * the same flush; delivery to keyed subscribers is batched on flush as usual.
  *
@@ -1900,7 +1919,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;
@@ -1951,7 +1971,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

@@ -1265,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;
@@ -1345,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);
   }
@@ -4225,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

@@ -203,7 +203,7 @@ rows.subscribeOnKey('team1', () => { for (const row of rows.getByKey('team1')) {
 
 ### Derived collections
 
-`OIMDerivedCollection(queue, source, derive, opts?)` is a reactive collection whose entities are derived **one-to-one** from a source collection — `derived[pk] = derive(source[pk], pk)`, keyed by the SOURCE pk — kept in sync (add / update / remove) automatically. It is itself a first-class `OIMReactiveCollection`, so it can be indexed, selected, and derived-from again (join → join); maintenance runs on the source's **synchronous** update channel, so a chain of derivations stays consistent within a flush (delivery to keyed subscribers is batched on flush as usual). It parallels `OIMDerivedCollectionIndex*` and needs no compute runtime.
+`OIMDerivedCollection(queue, source, derive, opts?)` is a reactive collection whose entities are derived **one-to-one** from a source collection — `derived[pk] = derive(source[pk], pk)`, keyed by the SOURCE pk — kept in sync (add / update / remove) automatically. It is itself a first-class `OIMReactiveCollection`, so it can be indexed, selected, and derived-from again — a CHAIN of one-to-one projections, NOT a join. There is deliberately no multi-source derived collection: a joined row would need a pk nobody references, and an identity nobody uses is not an identity; combine across collections with one `OIMComputed`, or give the combined thing its own collection if something genuinely references it; maintenance runs on the source's **synchronous** update channel, so a chain of derivations stays consistent within a flush (delivery to keyed subscribers is batched on flush as usual). It parallels `OIMDerivedCollectionIndex*` and needs no compute runtime.
 
 ```ts
 const nameView = new OIMDerivedCollection(queue, users,
@@ -395,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';
 
-// wrap any OIMSelector
-const alice = fromSelector(kit.select.byPk('u1')); // TExoBindable<User | undefined>
+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 });
+
+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) |
+| `exoRows(keys, 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`. `exoRows` 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 `exoRows` 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 key is IDENTITY, never invalidation — `key: t => t.id` and nothing else; a composite key re-derives the whole key sequence per read and rebuilds rows whose markup did not change (2000 rows, one added comment: 2.44ms + 1 wasted rebuild vs 0.73ms + zero when the count is bound inside the row), so bind what varies WITHIN a row via `derive(db.comments.byTask.pks(pk), c => c.length)`; `<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.1",
+  "version": "3.12.1",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",