@oimdb/core 1.5.0 → 2.0.0

package/README.md

@@ -2,6 +2,30 @@
 
 Core in-memory data library providing reactive collections, intelligent indexing, and configurable event processing. This package offers the foundational building blocks for building high-performance, event-driven in-memory databases with type-safe operations and automatic change notifications.
 
+## For AI Assistants
+
+If you are an AI assistant working on a project that uses OIMDB, read the full API reference before writing any code. It covers all packages, key concepts, code patterns, and naming conventions — the API has specific patterns that are easy to get wrong without context.
+
+The file ships with this package. Read it at:
+
+```
+node_modules/@oimdb/core/llms.txt
+```
+
+Or fetch from CDN if working without local files:
+
+```
+https://cdn.jsdelivr.net/npm/@oimdb/core/llms.txt
+```
+
+If the project has `@oimdb/devtools` installed, also look for `debug.ts` or `*.debug.ts` files — they register the app's specific collections, indexes, and computeds by name and describe their relations. This is the fastest way to understand the specific data model you're working with.
+
+**Cursor users:** Cursor does not index `node_modules`, so it will not find this README automatically. Add a `.cursor/rules/oimdb.mdc` file to your project:
+
+```
+Read node_modules/@oimdb/core/llms.txt before writing any OIMDB code.
+```
+
 ## 🚀 Installation
 
 ```bash
@@ -14,9 +38,13 @@ This package exports all the core classes, interfaces, and types needed to build
 
 ### Core Classes
 - **OIMReactiveCollection**: Reactive entity storage with automatic change notifications
-- **OIMRICollection**: Reactive collection with integrated indexing capabilities
+- **OIMCollectionRelations**: Helper for creating collection-bound indexes and ordered lists next to a collection
 - **OIMReactiveIndexManualSetBased**: Reactive index with Set-based storage (efficient for incremental updates)
 - **OIMReactiveIndexManualArrayBased**: Reactive index with Array-based storage (efficient for full replacements)
+- **OIMReactiveCollectionIndexManualSetBased**: Collection-bound Set-based index with safe PK-oriented writes
+- **OIMReactiveCollectionIndexManualArrayBased**: Collection-bound Array-based index with safe PK-oriented writes
+- **OIMOrderedListCommandStream**: Slot-first ordered per-key lists with incremental commands for imperative consumers
+- **OIMCollectionOrderedListCommandStream**: Collection-bound ordered lists with PK writes and slot/entity command payloads
 - **OIMEventQueue**: Configurable event processing queue with scheduler integration
 - **OIMCollection**: Base collection with CRUD operations and event emission
 
@@ -38,6 +66,7 @@ This package exports all the core classes, interfaces, and types needed to build
 - **OIMCollectionStoreMapDriven**: Map-based storage backend
 - **OIMIndexManualSetBased**: Set-based manual index (stores slots, projects to `Set<TPk>`)
 - **OIMIndexManualArrayBased**: Array-based manual index (stores slots, projects to `TPk[]`)
+- **OIMIndexManualOrderedArrayBased**: Slot-first manual ordered Array-based index with `pushSlot`, `insertSlotAt`, `removeAt`, `move`, and `resetSlots`
 - **OIMIndexStoreMapDrivenSetBased**: Set-based slot index storage backend
 - **OIMIndexStoreMapDrivenArrayBased**: Array-based slot index storage backend
 - **OIMMap2Keys**: Two-key mapping utilities for complex indexing
@@ -57,6 +86,43 @@ This package exports all the core classes, interfaces, and types needed to build
 
 ## 🔧 Basic Usage
 
+### DX Collection Model
+
+Use the `dx` factories when you want a concise entrypoint without changing the underlying model. The collection still owns entities, and relations still live next to it.
+
+```typescript
+import {
+    createOIMCollectionContext,
+    OIMEventQueue,
+    OIMEventQueueSchedulerFactory
+} from '@oimdb/core';
+
+type User = {
+    id: string;
+    name: string;
+    teamId: string;
+};
+
+const queue = new OIMEventQueue({
+    scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
+});
+const users = createOIMCollectionContext<User, string>(queue, {
+    selectPk: user => user.id,
+});
+
+const usersByTeam = users.indexFactory.derivedSetIndex(user => user.teamId);
+const teamUsers = users.select.entitiesBySetIndexKey(usersByTeam, 'team1');
+
+users.collection.upsertMany([
+    { id: 'u1', name: 'Alice', teamId: 'team1' },
+    { id: 'u2', name: 'Bob', teamId: 'team1' },
+]);
+
+teamUsers.watch(value => {
+    console.log(value); // Alice, Bob
+});
+```
+
 ### Creating a Reactive Collection
 
 ```typescript
@@ -92,35 +158,63 @@ users.updateEventEmitter.subscribeOnKeys(['user1', 'user2'], () => {
     console.log('Users changed!');
 });
 
-// CRUD operations
-users.upsertOne({ id: 'user1', name: 'John Doe', email: 'john@example.com' });
-users.upsertMany([
+// CRUD operations return canonical slots.
+const user1Slot = users.upsertOne({
+    id: 'user1',
+    name: 'John Doe',
+    email: 'john@example.com'
+});
+const otherSlots = users.upsertMany([
     { id: 'user2', name: 'Jane Smith', email: 'jane@example.com' },
     { id: 'user3', name: 'Bob Wilson', email: 'bob@example.com' }
 ]);
 
+// Updating an entity keeps the same slot object and updates slot.item.
+const updatedUser1Slot = users.upsertOne({
+    id: 'user1',
+    name: 'John Smith',
+    email: 'john@example.com'
+});
+console.log(user1Slot === updatedUser1Slot); // true
+
 // Query operations
 const user = users.getOneByPk('user1');
 const multipleUsers = users.getManyByPks(['user1', 'user2']);
+const userSlot = users.getSlotByPk('user1');
 ```
 
 ### Creating a Reactive Index
 
 OIMDB provides two types of indexes optimized for different use cases:
 
-Indexes are slot-backed internally. Collections own canonical `{ pk, item }` slots, while indexes store references to those slots. `getPksByKey` remains available as a PK projection (`Set<TPk>` for SetBased, `TPk[]` for ArrayBased), and entity-by-index selectors/hooks read `slot.item` directly for faster reads.
+Indexes are slot-backed internally and expose PK projections through `getPksByKey` (`Set<TPk>` for SetBased, `TPk[]` for ArrayBased). Raw indexes can be used as standalone PK/slot structures. When an index belongs to a collection, prefer `OIMReactiveCollectionIndexManual*`; it binds the collection at construction time so PK writes resolve canonical collection slots without a later lifecycle setter.
+
+For most app-level entity relations, start with `createOIMCollectionContext(...).indexFactory.derivedSetIndex(...)` or `.derivedArrayIndex(...)`. The manual indexes below are the advanced path for externally maintained memberships such as search results, permissions, or server-provided order.
 
 #### SetBased Indexes (for incremental updates)
 
 ```typescript
-import { OIMReactiveIndexManualSetBased, OIMEventQueue } from '@oimdb/core';
+import {
+    OIMReactiveCollection,
+    OIMReactiveCollectionIndexManualSetBased,
+    OIMEventQueue
+} from '@oimdb/core';
+
+type User = { id: string; role: string };
 
 // Create Set-based reactive index for user roles
 const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
 
-const userRoleIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const users = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (user) => user.id
+});
+const userRoleIndex =
+    new OIMReactiveCollectionIndexManualSetBased<string, string, User>(
+        queue,
+        { collection: users }
+    );
 
 // Subscribe to specific index key changes
 userRoleIndex.updateEventEmitter.subscribeOnKey('admin', () => {
@@ -145,14 +239,27 @@ userRoleIndex.removePks('admin', ['user1']);
 #### ArrayBased Indexes (for full replacements)
 
 ```typescript
-import { OIMReactiveIndexManualArrayBased, OIMEventQueue } from '@oimdb/core';
+import {
+    OIMReactiveCollection,
+    OIMReactiveCollectionIndexManualArrayBased,
+    OIMEventQueue
+} from '@oimdb/core';
+
+type Card = { id: string; deckId: string };
 
 // Create Array-based reactive index for deck cards
 const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
 
-const cardsByDeckIndex = new OIMReactiveIndexManualArrayBased<string, string>(queue);
+const cards = new OIMReactiveCollection<Card, string>(queue, {
+    selectPk: (card) => card.id
+});
+const cardsByDeckIndex =
+    new OIMReactiveCollectionIndexManualArrayBased<string, string, Card>(
+        queue,
+        { collection: cards }
+    );
 
 // Subscribe to specific index key changes
 cardsByDeckIndex.updateEventEmitter.subscribeOnKey('deck1', () => {
@@ -174,6 +281,68 @@ cardsByDeckIndex.setPks('deck1', ['card1', 'card2', 'card4']); // Full replaceme
 - **SetBased**: Use when you frequently add/remove individual items (`addPks`/`removePks` are efficient) and order doesn't matter
 - **ArrayBased**: Use when you typically replace the entire array (`setPks` is more efficient, no diff computation needed) or when you need to preserve element order/sorting
 
+#### Ordered List Command Streams
+
+Use `OIMCollectionOrderedListCommandStream` when you need an ordered list per key, PK-oriented writes, canonical collection slots, and incremental commands for an imperative renderer or external store. Use `OIMOrderedListCommandStream` directly only when you already manage slots yourself.
+
+```typescript
+import {
+    OIMEventQueue,
+    OIMReactiveCollection,
+    OIMCollectionOrderedListCommandStream
+} from '@oimdb/core';
+
+type Card = { id: string; title: string };
+
+const queue = new OIMEventQueue();
+const cards = new OIMReactiveCollection<Card, string>(queue, {
+    selectPk: card => card.id,
+});
+const cardsByDeck = new OIMCollectionOrderedListCommandStream<
+    string,
+    string,
+    Card
+>(queue, { collection: cards });
+
+cards.upsertMany([
+    { id: 'card1', title: 'Intro' },
+    { id: 'card2', title: 'Details' },
+    { id: 'card3', title: 'Summary' },
+]);
+
+cardsByDeck.commandsEventEmitter.subscribeOnKey('deck1', () => {
+    const commands = cardsByDeck.consumeCommands('deck1');
+
+    for (const command of commands) {
+        switch (command.type) {
+            case 'insert':
+                // Insert command.pk / command.slot.item at command.index
+                break;
+            case 'remove':
+                // Remove command.pk from command.index
+                break;
+            case 'move':
+                // Move command.pk from command.fromIndex to command.toIndex
+                break;
+            case 'set':
+                // Replace the whole list with command.pks or command.slots
+                break;
+        }
+    }
+});
+
+cardsByDeck.set('deck1', ['card1', 'card2']);
+cardsByDeck.move('deck1', 1, 0);
+cardsByDeck.push('deck1', 'card3');
+
+queue.flush(); // Delivers one batched command notification for deck1
+
+console.log(cardsByDeck.getPksByKey('deck1')); // ['card2', 'card1', 'card3']
+console.log(cardsByDeck.getEntitiesByKey('deck1')); // [{ id: 'card2', ... }, ...]
+```
+
+If you mutate `cardsByDeck.index` directly, the stream cannot know the exact operation and emits a `set` command so consumers can resync.
+
 ### Event Queue and Schedulers
 
 ```typescript
@@ -216,12 +385,13 @@ console.log('Is empty:', manualQueue.isEmpty);
 
 ## 🏗️ Advanced Usage
 
-### Reactive Collection with Indexes (OIMRICollection)
+### Collections with Bound Indexes
 
 ```typescript
 import { 
-    OIMRICollection, 
-    OIMReactiveIndexManual, 
+    OIMReactiveCollection,
+    OIMReactiveCollectionIndexManualSetBased,
+    OIMReactiveCollectionIndexManualArrayBased,
     OIMEventQueue,
     OIMEventQueueSchedulerFactory
 } from '@oimdb/core';
@@ -239,24 +409,28 @@ const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
 
-// Create indexes (choose SetBased or ArrayBased based on your needs)
-const teamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
-const roleIndex = new OIMReactiveIndexManualArrayBased<string, string>(queue);
-
-// Create collection with indexes
-const users = new OIMRICollection(queue, {
-    collectionOpts: {
-        selectPk: (user: User) => user.id
-    },
-    indexes: {
-        byTeam: teamIndex,
-        byRole: roleIndex
-    }
+// Collections own entities.
+const users = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (user: User) => user.id
 });
 
+// Indexes live next to collections and bind to them at construction time.
+const indexes = {
+    usersByTeam: new OIMReactiveCollectionIndexManualSetBased<
+        string,
+        string,
+        User
+    >(queue, { collection: users }),
+    usersByRole: new OIMReactiveCollectionIndexManualArrayBased<
+        string,
+        string,
+        User
+    >(queue, { collection: users })
+};
+
 // Subscribe to index changes
-users.indexes.byTeam.updateEventEmitter.subscribeOnKey('engineering', (pks) => {
-    console.log('Engineering team changed:', pks);
+indexes.usersByTeam.updateEventEmitter.subscribeOnKey('engineering', () => {
+    console.log('Engineering team changed:', indexes.usersByTeam.getPksByKey('engineering'));
 });
 
 // Add users and update indexes
@@ -266,8 +440,70 @@ users.upsertMany([
 ]);
 
 // Update indexes manually
-users.indexes.byTeam.setPks('engineering', ['u1', 'u2']);
-users.indexes.byRole.setPks('admin', ['u1']);
+indexes.usersByTeam.setPks('engineering', ['u1', 'u2']);
+indexes.usersByRole.setPks('admin', ['u1']);
+```
+
+### Collection Relations Helper
+
+Use `createOIMCollectionRelations` when you want the same clean model with less constructor noise. It does not store indexes inside the collection; it only keeps the shared `queue + collection` binding for related structures that live next to the collection.
+
+```typescript
+import {
+    createOIMCollectionRelations,
+    OIMReactiveCollection,
+    OIMEventQueue
+} from '@oimdb/core';
+
+type User = {
+    id: string;
+    name: string;
+    teamId: string;
+};
+
+type Card = {
+    id: string;
+    deckId: string;
+    position: number;
+};
+
+const queue = new OIMEventQueue();
+const users = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: user => user.id,
+});
+const userRelations = createOIMCollectionRelations(queue, users);
+const cards = new OIMReactiveCollection<Card, string>(queue, {
+    selectPk: card => card.id,
+});
+const cardRelations = createOIMCollectionRelations(queue, cards);
+
+// Derived indexes update themselves from collection writes.
+const usersByTeam = userRelations.derivedSetIndex(user => user.teamId);
+const cardsByDeck = cardRelations.derivedArrayIndex(
+    card => card.deckId,
+    { orderBy: card => card.position }
+);
+
+// Manual relations are still available when membership comes from outside.
+const searchResults = userRelations.arrayBasedIndex<string>();
+const orderedUsers = userRelations.orderedList<string>();
+
+users.upsertMany([
+    { id: 'u1', name: 'Alice', teamId: 'team1' },
+    { id: 'u2', name: 'Bob', teamId: 'team1' },
+]);
+cards.upsertMany([
+    { id: 'c1', deckId: 'deck1', position: 2 },
+    { id: 'c2', deckId: 'deck1', position: 1 },
+]);
+
+searchResults.setPks('query:alice', ['u1']);
+orderedUsers.set('visible', ['u1', 'u2']);
+queue.flush();
+
+console.log(usersByTeam.getEntitiesByKey('team1')); // Alice, Bob
+console.log(cardsByDeck.getPksByKey('deck1')); // ['c2', 'c1']
+console.log(orderedUsers.getPksByKey('visible')); // ['u1', 'u2']
 ```
 
 ### Custom Entity Updater
@@ -454,13 +690,25 @@ import {
   OIMEffect,
   OIMComputativeRuntime,
   OIMEventQueue,
-  OIMReactiveIndexManualSetBased,
+  OIMReactiveCollection,
+  OIMReactiveCollectionIndexManualSetBased,
   OIMEffectDependencyKeyedIndex,
 } from '@oimdb/core';
 
+interface User {
+  id: string;
+  name: string;
+}
+
 const queue = new OIMEventQueue();
 const runtime = new OIMComputativeRuntime(queue);
-const roleIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const users = new OIMReactiveCollection<User, string>(queue, {
+  selectPk: (u) => u.id,
+});
+const roleIndex = new OIMReactiveCollectionIndexManualSetBased<string, string, User>(
+  queue,
+  { collection: users }
+);
 
 const effect = new OIMEffect(runtime, {
   deps: [new OIMEffectDependencyKeyedIndex(roleIndex, 'admin')],
@@ -470,11 +718,16 @@ const effect = new OIMEffect(runtime, {
   },
 });
 
+users.upsertMany([
+  { id: 'user1', name: 'Alice' },
+  { id: 'user2', name: 'Bob' },
+]);
 roleIndex.setPks('admin', ['user1', 'user2']);
 queue.flush();
 
 effect.destroy();
 roleIndex.destroy();
+users.destroy();
 queue.destroy();
 ```
 
@@ -572,7 +825,7 @@ import {
   OIMEventQueue,
   OIMComputativeRuntime,
   OIMReactiveCollection,
-  OIMReactiveIndexManualSetBased,
+  OIMReactiveCollectionIndexManualSetBased,
   OIMEffectDependencyKeyedCollection,
   OIMEffectDependencyKeyedIndex,
 } from '@oimdb/core';
@@ -588,7 +841,10 @@ const runtime = new OIMComputativeRuntime(queue);
 const users = new OIMReactiveCollection<User, string>(queue, {
   selectPk: (u) => u.id,
 });
-const roleIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const roleIndex = new OIMReactiveCollectionIndexManualSetBased<string, string, User>(
+  queue,
+  { collection: users }
+);
 
 // Computed that counts admin users
 const adminCount = new OIMComputed<number>(runtime, {
@@ -736,7 +992,7 @@ import {
   OIMComputativeRuntime,
   OIMEventQueue,
   OIMReactiveCollection,
-  OIMReactiveIndexManualSetBased,
+  OIMReactiveCollectionIndexManualSetBased,
 } from '@oimdb/core';
 
 const queue = new OIMEventQueue();
@@ -744,7 +1000,10 @@ const runtime = new OIMComputativeRuntime(queue);
 const users = new OIMReactiveCollection<User, string>(queue, {
   selectPk: (u) => u.id,
 });
-const roleIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const roleIndex = new OIMReactiveCollectionIndexManualSetBased<string, string, User>(
+  queue,
+  { collection: users }
+);
 
 // Watch all admin users
 const adminUsersSelector = new OIMEntitiesByIndexKeySetBasedSelector(
@@ -835,17 +1094,23 @@ Choose the right scheduler for your use case:
 ### Reactive Collection Hierarchy
 
 ```
-OIMCollection (base)
-├── OIMReactiveCollection (adds updateEventEmitter wired to the queue)
-└── OIMRICollection (reactive collection + indexes)
+OIMCollection (base; upserts return canonical slots)
+└── OIMReactiveCollection (adds updateEventEmitter wired to the queue)
 
 OIMIndexSetBased (base for Set-based)
 ├── OIMIndexManualSetBased (manual Set-based index)
-└── OIMReactiveIndexManualSetBased (reactive Set-based index with event emitter)
+├── OIMReactiveIndexManualSetBased (reactive Set-based index with event emitter)
+└── OIMReactiveCollectionIndexManualSetBased (collection-bound reactive Set-based index)
 
 OIMIndexArrayBased (base for Array-based)
 ├── OIMIndexManualArrayBased (manual Array-based index)
-└── OIMReactiveIndexManualArrayBased (reactive Array-based index with event emitter)
+├── OIMIndexManualOrderedArrayBased (slot-first manual ordered Array-based index)
+├── OIMCollectionIndexManualOrderedArrayBased (collection-bound ordered Array-based index)
+├── OIMReactiveIndexManualArrayBased (reactive Array-based index with event emitter)
+└── OIMReactiveCollectionIndexManualArrayBased (collection-bound reactive Array-based index)
+
+OIMOrderedListCommandStream (slot-first ordered-list command stream)
+OIMCollectionOrderedListCommandStream (collection-bound ordered-list command stream)
 ```
 
 ## ⚡ Performance Characteristics
@@ -863,7 +1128,7 @@ OIMIndexArrayBased (base for Array-based)
 
 ### Index Performance
 
-**SetBased Indexes** (`OIMReactiveIndexManualSetBased`):
+**SetBased Indexes** (`OIMReactiveCollectionIndexManualSetBased`):
 - **Storage**: Set of canonical entity slots
 - **PK projection**: `getPksByKey` returns `Set<TPk>` for efficient membership checks
 - **Entity reads**: selectors/hooks read `slot.item` directly, avoiding per-item collection lookups
@@ -871,7 +1136,7 @@ OIMIndexArrayBased (base for Array-based)
 - **Performance**: O(1) add/remove operations, O(n) for `setPks` (requires Set creation)
 - **Use case**: When you need to frequently add/remove individual items
 
-**ArrayBased Indexes** (`OIMReactiveIndexManualArrayBased`):
+**ArrayBased Indexes** (`OIMReactiveCollectionIndexManualArrayBased`):
 - **Storage**: Array of canonical entity slots
 - **PK projection**: `getPksByKey` returns `TPk[]` for direct array access
 - **Entity reads**: selectors/hooks read `slot.item` directly, preserving array order
@@ -884,16 +1149,60 @@ OIMIndexArrayBased (base for Array-based)
 
 ### With React (@oimdb/react)
 
-The core library integrates seamlessly with React through dedicated hooks:
+```bash
+npm install @oimdb/react
+```
+
+Create your collections outside React, wire them up once, then use hooks inside components:
 
 ```typescript
-import { useSelectEntitiesByPks, selectEntityByPk } from '@oimdb/react';
+import { createOIMCollectionContext, OIMEventQueue } from '@oimdb/core';
+import {
+    OIMCollectionsProvider,
+    useOIMCollectionsContext,
+    useSelectEntityByPk,
+    useSelectEntitiesByIndexKeySetBased,
+} from '@oimdb/react';
+
+// --- store.ts (created once, outside React) ---
+const queue = new OIMEventQueue();
+const { collection: users, indexFactory } =
+    createOIMCollectionContext<User, string>(queue, { selectPk: (u) => u.id });
+const byTeam = indexFactory.derivedSetIndex((u) => [u.teamId]);
+export const collections = { users };
+export { byTeam };
+
+// --- App.tsx ---
+function App() {
+    return (
+        <OIMCollectionsProvider collections={collections}>
+            <TeamList teamId="team1" />
+        </OIMCollectionsProvider>
+    );
+}
 
-// React hooks automatically subscribe to reactive collections
-const user = selectEntityByPk(users, 'user1');
-const teamUsers = useSelectEntitiesByPks(users, userIds);
+// --- TeamList.tsx ---
+type AppCollections = typeof collections;
+
+function TeamList({ teamId }: { teamId: string }) {
+    const { users } = useOIMCollectionsContext<AppCollections>();
+    const members = useSelectEntitiesByIndexKeySetBased(users, byTeam, teamId);
+    return (
+        <ul>
+            {members?.map((u) => u && <li key={u.id}>{u.name}</li>)}
+        </ul>
+    );
+}
+
+function UserCard({ userId }: { userId: string }) {
+    const { users } = useOIMCollectionsContext<AppCollections>();
+    const user = useSelectEntityByPk(users, userId);
+    return <span>{user?.name}</span>;
+}
 ```
 
+All hooks use `useSyncExternalStore` internally and re-render only when the specific data they watch actually changes.
+
 ### With Redux (@oimdb/redux-adapter)
 
 Migrate from Redux to OIMDB gradually or use both systems side-by-side with automatic two-way synchronization:
@@ -952,6 +1261,34 @@ unsubscribe();
 
 ## 📚 API Reference
 
+### DX Factories
+
+#### `createOIMReactiveCollection<TEntity, TPk>(queue, opts?)`
+Creates an `OIMReactiveCollection<TEntity, TPk>` with less constructor noise.
+
+#### `createOIMCollectionContext<TEntity, TPk>(queue, opts?)`
+Creates a small facade:
+
+```typescript
+type TOIMCollectionContext<TEntity, TPk> = {
+    queue: OIMEventQueue;
+    collection: OIMReactiveCollection<TEntity, TPk>;
+    relations: OIMCollectionRelations<TEntity, TPk>;
+    select: OIMCollectionSelectors<TEntity, TPk>;
+};
+```
+
+This is a DX entrypoint only: indexes and lists are still created as separate relation objects, not stored inside the collection.
+
+#### `OIMCollectionSelectors<TEntity, TPk>`
+DX facade for reactive read selectors backed by one `OIMComputativeRuntime`.
+
+**Methods:**
+- `byPk(pk)` - Create `OIMCollectionByPkSelector<TEntity, TPk>`
+- `byPks(pks)` - Create `OIMCollectionByPksSelector<TEntity, TPk>`
+- `entitiesBySetIndexKey(index, key)` - Create an entity selector for a Set-based reactive index key
+- `entitiesByArrayIndexKey(index, key)` - Create an entity selector for an Array-based reactive index key
+
 ### Core Classes
 
 #### `OIMReactiveCollection<TEntity, TPk>`
@@ -968,8 +1305,9 @@ new OIMReactiveCollection(queue: OIMEventQueue, opts?: TOIMCollectionOptions<TEn
 - Event batching/deduplication is handled internally by `OIMUpdateEventEmitter`
 
 **Methods:**
-- `upsertOne(entity: TEntity): void` - Insert or update single entity
-- `upsertMany(entities: TEntity[]): void` - Insert or update multiple entities
+- `upsertOne(entity: TEntity): TOIMEntitySlot<TEntity, TPk>` - Insert or update single entity and return its canonical slot
+- `upsertOneByPk(pk: TPk, entity: Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>` - Insert or update by primary key and return its canonical slot
+- `upsertMany(entities: TEntity[]): TOIMEntitySlot<TEntity, TPk>[]` - Insert or update multiple entities and return canonical slots
 - `removeOne(entity: TEntity): void` - Remove single entity
 - `removeMany(entities: TEntity[]): void` - Remove multiple entities
 - `getOneByPk(pk: TPk): TEntity | undefined` - Get entity by primary key
@@ -977,23 +1315,29 @@ new OIMReactiveCollection(queue: OIMEventQueue, opts?: TOIMCollectionOptions<TEn
 - `getSlotByPk(pk: TPk): OIMEntitySlot<TEntity, TPk> | undefined` - Get the canonical slot for a primary key
 - `getSlotsByPks(pks: readonly TPk[]): OIMEntitySlot<TEntity, TPk>[]` - Get existing canonical slots for primary keys
 
-#### `OIMRICollection<TEntity, TPk, TIndexName, TIndexKey, TIndex, TReactiveIndex, TReactiveIndexMap>`
-Reactive collection with integrated indexing capabilities.
+#### `OIMCollectionRelations<TEntity, TPk>`
+Factory helper for collection-bound relations. It keeps `queue + collection` together for construction only; created indexes/lists still live next to the collection, not inside it.
 
 **Constructor:**
 ```typescript
-new OIMRICollection(queue: OIMEventQueue, opts: {
-    collectionOpts?: TOIMCollectionOptions<TEntity, TPk>;
-    indexes: TReactiveIndexMap;
-})
+new OIMCollectionRelations(queue: OIMEventQueue, collection: OIMReactiveCollection<TEntity, TPk>)
 ```
 
-**Properties:**
-- `indexes: TReactiveIndexMap` - Named reactive indexes preserving index-to-name mapping
-- *(inherits all OIMReactiveCollection properties)*
+**Factory:**
+```typescript
+createOIMCollectionRelations(queue, collection)
+```
+
+**Methods:**
+- `setBasedIndex<TKey>()` - Create `OIMReactiveCollectionIndexManualSetBased<TKey, TPk, TEntity>`
+- `derivedSetIndex<TKey>(selectIndexKeys)` - Create `OIMDerivedCollectionIndexSetBased<TKey, TPk, TEntity>`
+- `arrayBasedIndex<TKey>()` - Create `OIMReactiveCollectionIndexManualArrayBased<TKey, TPk, TEntity>`
+- `derivedArrayIndex<TKey>(selectIndexKeys, { orderBy?, compareEntities? })` - Create `OIMDerivedCollectionIndexArrayBased<TKey, TPk, TEntity>`
+- `orderedIndex<TKey>()` - Create `OIMCollectionIndexManualOrderedArrayBased<TKey, TPk, TEntity>`
+- `orderedList<TKey>()` - Create `OIMCollectionOrderedListCommandStream<TKey, TPk, TEntity>`
 
 #### `OIMReactiveIndexManualSetBased<TKey, TPk>`
-Reactive Set-based index with manual key-to-entity mapping and change notifications. Stores canonical slots internally and projects to `Set<TPk>` for PK reads.
+Reactive Set-based index with manual slot writes and change notifications. Use this as a raw slot-first primitive; use `OIMReactiveCollectionIndexManualSetBased` for PK-oriented writes.
 
 **Constructor:**
 ```typescript
@@ -1001,7 +1345,6 @@ new OIMReactiveIndexManualSetBased(queue: OIMEventQueue, opts?: {
     indexOptions?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreSetBased<TKey, TPk>;
-        resolveSlot?: TOIMEntitySlotResolver<TPk>;
     }
 })
 ```
@@ -1011,9 +1354,6 @@ new OIMReactiveIndexManualSetBased(queue: OIMEventQueue, opts?: {
 - `updateEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific subscriptions
 
 **Methods:**
-- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key (replaces entire Set)
-- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key (efficient)
-- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key (efficient)
 - `setSlots(key: TKey, slots: Iterable<TOIMAnyEntitySlot<TPk>>): void` - Set canonical slots directly
 - `clear(key?: TKey): void` - Clear all keys or specific key
 
@@ -1021,8 +1361,56 @@ new OIMReactiveIndexManualSetBased(queue: OIMEventQueue, opts?: {
 - `index.getPksByKey(key: TKey): Set<TPk>` - Returns Set projection of primary keys
 - `index.getSlotsByKey(key: TKey): ReadonlySet<TOIMAnyEntitySlot<TPk>>` - Returns stored slots for fast entity reads
 
+#### `OIMReactiveCollectionIndexManualSetBased<TKey, TPk, TEntity>`
+Collection-bound Set-based index. Use this when `setPks`/`addPks`/`removePks` should resolve PKs to canonical slots from a collection.
+
+**Constructor:**
+```typescript
+new OIMReactiveCollectionIndexManualSetBased(queue: OIMEventQueue, opts: {
+    collection: OIMReactiveCollection<TEntity, TPk>;
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TKey, TPk>;
+    };
+} | {
+    resolveSlot: TOIMEntitySlotResolver<TPk>;
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TKey, TPk>;
+    };
+})
+```
+
+Pass exactly one binding: `collection` for normal collection-bound indexes, or `resolveSlot` for custom slot resolution.
+
+**Methods:**
+- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key
+- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key
+- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key
+- `setSlots(key: TKey, slots: Iterable<TOIMAnyEntitySlot<TPk>>): void` - Set canonical slots directly
+- `clear(key?: TKey): void` - Clear all keys or specific key
+
+#### `OIMDerivedCollectionIndexSetBased<TKey, TPk, TEntity>`
+Collection-bound Set-based index that derives membership from collection entities. Use this when index keys come from entity fields and should stay in sync automatically.
+
+**Constructor:**
+```typescript
+new OIMDerivedCollectionIndexSetBased(queue, collection, {
+    selectIndexKeys: (entity: TEntity) => TKey | readonly TKey[] | undefined | null;
+    buildInitial?: boolean; // defaults to true
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TKey, TPk>;
+    };
+})
+```
+
+**Methods:**
+- `rebuildFromCollection(): void` - Rebuild all derived membership from current collection slots
+- all read/subscription methods from `OIMReactiveCollectionIndexManualSetBased`
+
 #### `OIMReactiveIndexManualArrayBased<TKey, TPk>`
-Reactive Array-based index with manual key-to-entity mapping and change notifications. Stores canonical slots internally and projects to `TPk[]` for PK reads.
+Reactive Array-based index with manual slot writes and change notifications. Use this as a raw slot-first primitive; use `OIMReactiveCollectionIndexManualArrayBased` for PK-oriented writes.
 
 **Constructor:**
 ```typescript
@@ -1030,7 +1418,6 @@ new OIMReactiveIndexManualArrayBased(queue: OIMEventQueue, opts?: {
     indexOptions?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreArrayBased<TKey, TPk>;
-        resolveSlot?: TOIMEntitySlotResolver<TPk>;
     }
 })
 ```
@@ -1040,9 +1427,6 @@ new OIMReactiveIndexManualArrayBased(queue: OIMEventQueue, opts?: {
 - `updateEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific subscriptions
 
 **Methods:**
-- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key (direct assignment, no diff) - **Recommended for ArrayBased**
-- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key (O(n) operation, less efficient than SetBased)
-- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key (O(n) operation, less efficient than SetBased)
 - `setSlots(key: TKey, slots: TOIMAnyEntitySlot<TPk>[]): void` - Set canonical slots directly
 - `clear(key?: TKey): void` - Clear all keys or specific key
 
@@ -1052,6 +1436,126 @@ new OIMReactiveIndexManualArrayBased(queue: OIMEventQueue, opts?: {
 
 **Note**: While `addPks`/`removePks` are available, they require array operations (Set creation, filtering) making them O(n) compared to O(1) for SetBased indexes. For ArrayBased indexes, prefer `setPks` for better performance when replacing the entire array.
 
+#### `OIMDerivedCollectionIndexArrayBased<TKey, TPk, TEntity>`
+Collection-bound Array-based index that derives ordered membership from collection entities. Use this for UI lists where entities define both grouping and order.
+
+**Constructor:**
+```typescript
+new OIMDerivedCollectionIndexArrayBased(queue, collection, {
+    selectIndexKeys: (entity: TEntity) => TKey | readonly TKey[] | undefined | null;
+    buildInitial?: boolean; // defaults to true
+    orderBy?: (entity: TEntity) => string | number | bigint | boolean;
+    compareEntities?: (a: TEntity, b: TEntity) => number;
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreArrayBased<TKey, TPk>;
+    };
+})
+```
+
+`compareEntities` takes priority over `orderBy`. Without either option, arrays keep collection slot iteration order.
+
+**Methods:**
+- `rebuildFromCollection(): void` - Rebuild all derived ordered membership from current collection slots
+- all read/subscription methods from `OIMReactiveCollectionIndexManualArrayBased`
+
+#### `OIMReactiveCollectionIndexManualArrayBased<TKey, TPk, TEntity>`
+Collection-bound Array-based index. Use this when ordered PK arrays should resolve to canonical slots from a collection.
+
+**Constructor:**
+```typescript
+new OIMReactiveCollectionIndexManualArrayBased(queue: OIMEventQueue, opts: {
+    collection: OIMReactiveCollection<TEntity, TPk>;
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreArrayBased<TKey, TPk>;
+    };
+} | {
+    resolveSlot: TOIMEntitySlotResolver<TPk>;
+    indexOptions?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreArrayBased<TKey, TPk>;
+    };
+})
+```
+
+Pass exactly one binding: `collection` for normal collection-bound indexes, or `resolveSlot` for custom slot resolution.
+
+**Methods:**
+- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key
+- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key
+- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key
+- `setSlots(key: TKey, slots: TOIMAnyEntitySlot<TPk>[]): void` - Set canonical slots directly
+- `clear(key?: TKey): void` - Clear all keys or specific key
+
+#### `OIMIndexManualOrderedArrayBased<TKey, TPk>`
+Slot-first manual ordered Array-based index with direct list operations and update events. Use this when you need low-level ordered storage without a command stream.
+
+**Constructor:**
+```typescript
+new OIMIndexManualOrderedArrayBased<TKey, TPk>()
+```
+
+**Methods:**
+- `pushSlot(key: TKey, slot: TOIMAnyEntitySlot<TPk>): number` - Append a slot and return its inserted index
+- `insertSlotAt(key: TKey, index: number, slot: TOIMAnyEntitySlot<TPk>): number` - Insert a slot at an index, clamped to the list bounds
+- `removeAt(key: TKey, index: number): TOIMAnyEntitySlot<TPk> | undefined` - Remove and return the slot at an index
+- `move(key: TKey, fromIndex: number, toIndex: number): TOIMAnyEntitySlot<TPk> | undefined` - Move a slot within the list
+- `resetSlots(key: TKey, slots: readonly TOIMAnyEntitySlot<TPk>[]): void` - Replace the whole ordered slot list for a key
+- `clear(key?: TKey): void` - Clear all keys or a specific key
+
+**Query:**
+- `getPksByKey(key: TKey): TPk[]` - Returns the ordered primary-key array
+- `getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[]` - Returns the stored ordered slots
+- `getEntitiesByKey<TEntity>(key: TKey): TEntity[]` - Returns existing entities from stored slots
+
+#### `OIMCollectionIndexManualOrderedArrayBased<TKey, TPk, TEntity>`
+Collection-bound ordered Array-based index. Use this when ordered PK writes should resolve to canonical slots from a collection.
+
+**Methods:**
+- `push(key: TKey, pk: TPk): number` - Append a PK as its canonical slot
+- `insertAt(key: TKey, index: number, pk: TPk): number` - Insert a PK as its canonical slot
+- `reset(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs
+- `getEntitiesByKey(key: TKey): TEntity[]` - Returns entities from canonical slots
+
+#### `OIMOrderedListCommandStream<TKey, TPk, TEntity>`
+Slot-first ordered per-key list with a command stream for imperative consumers. It stores data in an `OIMIndexManualOrderedArrayBased` and emits `TOIMOrderedListCommand` batches through `commandsEventEmitter`.
+
+**Constructor:**
+```typescript
+new OIMOrderedListCommandStream(
+    queue: OIMEventQueue,
+    index?: OIMIndexManualOrderedArrayBased<TKey, TPk>
+)
+```
+
+**Properties:**
+- `index: OIMIndexManualOrderedArrayBased<TKey, TPk>` - Underlying ordered index and source of truth
+- `commandsEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific command notifications delivered after queue flush
+
+**Methods:**
+- `setSlots(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void` - Replace the whole ordered list and emit a `set` command
+- `pushSlot(key: TKey, slot: TOIMEntitySlot<TEntity, TPk>): void` - Append a slot and emit an `insert` command
+- `insertSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void` - Insert a slot and emit an `insert` command
+- `removeAt(key: TKey, index: number): void` - Remove by index and emit a `remove` command
+- `move(key: TKey, fromIndex: number, toIndex: number): void` - Move within the list and emit a `move` command
+- `consumeCommands(key: TKey): TOIMOrderedListCommand<TPk, TEntity>[]` - Read buffered commands for a key inside the notification handler
+- `getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[]` - Peek at buffered commands without clearing them
+- `getPksByKey(key: TKey): readonly TPk[]` - Read the current ordered list
+- `getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[]` - Read current ordered slots
+- `getEntitiesByKey(key: TKey): TEntity[]` - Read current ordered entities
+- `clear(key?: TKey): void` - Clear all keys or a specific key
+- `destroy(): void` - Dispose subscriptions and clear state
+
+#### `OIMCollectionOrderedListCommandStream<TKey, TPk, TEntity>`
+Collection-bound ordered-list command stream. Public writes use PKs, commands include both `pk`/`pks` and canonical `slot`/`slots`.
+
+**Methods:**
+- `set(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs
+- `push(key: TKey, pk: TPk): void` - Append a PK
+- `insertAt(key: TKey, index: number, pk: TPk): void` - Insert a PK
+- all read/command methods from `OIMOrderedListCommandStream`
+
 #### `OIMEventQueue`
 Event processing queue with configurable scheduling.