@myko/core 6.1.0 → 6.3.0

package/dist/graph-client.js

@@ -0,0 +1,192 @@
+import { combineLatest, map } from 'rxjs';
+import { LiveIndex } from './live-collection.js';
+function descriptorSchema(graph) {
+    const schema = graph.$schema;
+    if (!schema || typeof schema !== 'object')
+        return null;
+    const candidate = schema;
+    if ((candidate.pairProjection !== 'intersectAdjacency' &&
+        candidate.pairProjection !== 'eager') ||
+        (candidate.aAdjacency !== 'demandDriven' &&
+            candidate.aAdjacency !== 'eager') ||
+        (candidate.bAdjacency !== 'demandDriven' &&
+            candidate.bAdjacency !== 'eager')) {
+        return null;
+    }
+    return candidate;
+}
+function endpointPlan(schema, position) {
+    if (!schema) {
+        return {
+            strategy: 'unknown',
+            initialization: 'unknown',
+            liveUpdates: 'unknown',
+            windowing: 'unknown',
+            reason: 'This graph descriptor predates generated schema metadata.',
+        };
+    }
+    const adjacency = position === 'a' ? schema.aAdjacency : schema.bAdjacency;
+    if (adjacency === 'eager') {
+        return {
+            strategy: 'eagerEndpoint',
+            initialization: 'indexLookup',
+            liveUpdates: 'routed',
+            windowing: 'pushdown',
+            reason: `Endpoint ${position.toUpperCase()} has an eager adjacency projection.`,
+        };
+    }
+    return {
+        strategy: 'demandDrivenScan',
+        initialization: 'canonicalScan',
+        liveUpdates: 'routed',
+        windowing: 'materialized',
+        reason: `Endpoint ${position.toUpperCase()} is demand-driven; initialization scans canonical edges.`,
+    };
+}
+function pairPlan(schema) {
+    if (!schema)
+        return endpointPlan(null, 'a');
+    if (schema.pairProjection === 'eager') {
+        return {
+            strategy: 'eagerPair',
+            initialization: 'indexLookup',
+            liveUpdates: 'routed',
+            windowing: 'pushdown',
+            reason: 'Exact endpoint pairs have an eager pair projection.',
+        };
+    }
+    if (schema.aAdjacency === 'eager' || schema.bAdjacency === 'eager') {
+        return {
+            strategy: 'adjacencyFilter',
+            initialization: 'indexLookup',
+            liveUpdates: 'routed',
+            windowing: 'materialized',
+            reason: 'Exact pairs filter the available eager endpoint adjacency.',
+        };
+    }
+    return {
+        strategy: 'demandDrivenScan',
+        initialization: 'canonicalScan',
+        liveUpdates: 'routed',
+        windowing: 'materialized',
+        reason: 'Exact pairs have no eager projection; initialization scans canonical edges.',
+    };
+}
+function factory(graph, key) {
+    const candidate = graph[key];
+    if (typeof candidate !== 'function') {
+        throw new TypeError(`Graph helper '${key}' is not available`);
+    }
+    return candidate;
+}
+/** Bind generated graph query/report/command factories to a client instance. */
+export function bindGraph(client, graph) {
+    const schema = descriptorSchema(graph);
+    const plans = Object.freeze({
+        a: Object.freeze(endpointPlan(schema, 'a')),
+        b: Object.freeze(endpointPlan(schema, 'b')),
+        pair: Object.freeze(pairPlan(schema)),
+    });
+    const queryState = (key, args, options) => client.watchQueryState(factory(graph, key)(...args), options);
+    const reportState = (key, args) => client.watchReport(factory(graph, key)(...args));
+    const querySelection = (key, args, select, options) => client.watchQuerySelection(factory(graph, key)(...args), select, options);
+    const queryItem = (key, args, id, options) => client.watchQueryItem(factory(graph, key)(...args), id, options);
+    const queryHas = (key, args, id, options) => client.watchQueryHas(factory(graph, key)(...args), id, options);
+    const command = (key, args, options) => client.sendCommand(factory(graph, key)(...args), options);
+    const windowed = (key, args, window) => client.watchQueryWindowed(factory(graph, key)(...args), { window });
+    const cursor = (key, args, limit) => client.watchQueryCursor(factory(graph, key)(...args), limit);
+    const queryIndex = (key, args, keyOf, options) => {
+        const index = new LiveIndex(keyOf);
+        return queryState(key, args, options).pipe(map((state) => index.update(state)));
+    };
+    const endpoint = (edgeKey, exactEdgeKey, exactIdsKey, relatedKey, relatedName, countKey, traversalKey, syncKey, args, plan) => {
+        const exactEdgeQuery = (id) => exactEdgeKey && exactEdgeKey in graph
+            ? { key: exactEdgeKey, args: [...args, id] }
+            : { key: edgeKey, args };
+        const scope = {
+            plan,
+            edges: (options) => queryState(edgeKey, args, options),
+            selectEdges: (select, options) => querySelection(edgeKey, args, select, options),
+            edge: (id, options) => {
+                const exact = exactEdgeQuery(id);
+                return queryItem(exact.key, exact.args, id, options);
+            },
+            hasEdge: (id, options) => {
+                const exact = exactEdgeQuery(id);
+                return queryHas(exact.key, exact.args, id, options);
+            },
+            edgesWindowed: (window) => windowed(edgeKey, args, window),
+            edgesCursor: (limit) => cursor(edgeKey, args, limit),
+            edgesBy: (keyOf, options) => queryIndex(edgeKey, args, keyOf, options),
+        };
+        if (exactIdsKey && exactIdsKey in graph) {
+            scope.edgesByIds = (ids, options) => queryState(exactIdsKey, [...args, ids], options);
+        }
+        if (relatedKey in graph) {
+            const capitalizedName = relatedName === 'targets' ? 'Targets' : 'Sources';
+            const singularName = relatedName === 'targets' ? 'target' : 'source';
+            scope[relatedName] = (options) => queryState(relatedKey, args, options);
+            scope[`select${capitalizedName}`] = (select, options) => querySelection(relatedKey, args, select, options);
+            scope[singularName] = (id, options) => queryItem(relatedKey, args, id, options);
+            scope[`has${capitalizedName.slice(0, -1)}`] = (id, options) => queryHas(relatedKey, args, id, options);
+            scope[`${relatedName}Windowed`] = (window) => windowed(relatedKey, args, window);
+            scope.connections = (relatedId, options) => combineLatest([
+                queryState(edgeKey, args, options),
+                queryState(relatedKey, args, options),
+            ]).pipe(map(([edges, entities]) => edges.toArray().flatMap((edge) => {
+                const entity = entities.get(relatedId(edge));
+                return entity ? [{ edge, entity }] : [];
+            })));
+        }
+        if (countKey) {
+            scope.count = () => reportState(countKey, args);
+        }
+        if (traversalKey && traversalKey in graph) {
+            scope.traverse = (options) => reportState(traversalKey, [...args, options]);
+        }
+        if (syncKey && syncKey in graph) {
+            scope.sync = (edges, scopeOrOptions, maybeOptions) => {
+                const syncFactory = factory(graph, syncKey);
+                return syncFactory.length === 2
+                    ? command(syncKey, [args[0], edges], scopeOrOptions)
+                    : command(syncKey, [args[0], scopeOrOptions, edges], maybeOptions);
+            };
+        }
+        return scope;
+    };
+    const bound = {
+        schema,
+        from: (value) => endpoint('from', 'fromId', 'fromIds', 'targetsFrom', 'targets', 'countFrom', 'traverseFrom', 'syncFrom', [value], plans.a),
+        to: (value) => endpoint('to', 'toId', 'toIds', 'sourcesTo', 'sources', 'countTo', 'traverseTo', 'syncTo', [value], plans.b),
+        between: (a, b) => ({
+            plan: plans.pair,
+            edges: (options) => queryState('between', [a, b], options),
+            selectEdges: (select, options) => querySelection('between', [a, b], select, options),
+            edge: (id, options) => 'betweenId' in graph
+                ? queryItem('betweenId', [a, b, id], id, options)
+                : queryItem('between', [a, b], id, options),
+            hasEdge: (id, options) => 'betweenId' in graph
+                ? queryHas('betweenId', [a, b, id], id, options)
+                : queryHas('between', [a, b], id, options),
+            edgesWindowed: (window) => windowed('between', [a, b], window),
+            edgesCursor: (limit) => cursor('between', [a, b], limit),
+            count: () => reportState('countBetween', [a, b]),
+            exists: () => reportState('existsBetween', [a, b]),
+            ...('betweenIds' in graph
+                ? {
+                    edgesByIds: (ids, options) => queryState('betweenIds', [a, b, ids], options),
+                }
+                : {}),
+        }),
+        connect: (edge, options) => command('connect', [edge], options),
+        connectMany: (edges, options) => command('connectMany', [edges], options),
+        ensure: (edge, options) => command('ensure', [edge], options),
+        disconnect: (id, options) => command('disconnect', [id], options),
+        disconnectMany: (ids, options) => command('disconnectMany', [ids], options),
+    };
+    if ('fromMany' in graph) {
+        bound.fromMany = (values) => endpoint('fromMany', null, null, 'targetsFromMany', 'targets', null, null, null, [values], plans.a);
+        bound.toMany = (values) => endpoint('toMany', null, null, 'sourcesToMany', 'sources', null, null, null, [values], plans.b);
+    }
+    return bound;
+}

package/dist/index.d.ts

@@ -4,8 +4,10 @@
  * Browser-compatible WebSocket client with RxJS Observables,
  * plus Rust-generated type bindings.
  */
-import type { ID, MEvent, WrappedItem, ItemStub, LogLevel } from './generated';
+import type { ID, ItemStub, LogLevel, MEvent, WrappedItem } from './generated';
 export * from './generated';
+export { type BoundGraph, bindGraph, type GraphDescriptorSchema, type GraphQueryPlan, type WindowedGraphQuery, } from './graph-client.js';
+export { applyCollectionDiff, type CollectionChanges, type CollectionDiff, type Identified, LiveCollection, type LiveCollectionStatus, LiveIndex, type LiveIndexChanges, type MutableKeyedCollection, } from './live-collection.js';
 export type { LogLevel };
 /**
  * Get the item type name from an entity type or query class.
@@ -46,7 +48,7 @@ export declare const LOG_RANK: readonly ["ERROR", "WARN", "INFO", "DEBUG", "VERB
  * GetEventLog is now ServerEventLog in the Rust system.
  * @deprecated Use ServerEventLog from ./generated instead
  */
-export { ConnectionStatus, MykoClient, MykoProtocol, type ClientStats, type Command, type CommandResult, type MykoError, type MykoErrorEvent, type Query, type QueryDiff, type QueryItem, type QueryWatchOptions, type QueryWindow, type QueryWindowInfo, type QueryResult, type View, type ViewItem, type ViewResult, type Report, type ReportResult, } from './client.js';
+export { type ClientStats, type Command, type CommandOptions, type CommandResult, ConnectionStatus, MykoClient, type MykoError, type MykoErrorEvent, MykoProtocol, type Query, type QueryDiff, type QueryItem, type QueryResult, type QuerySelectionOptions, type QueryWatchOptions, type QueryWindow, type QueryWindowInfo, type QueryCursorWindow, type QueryCursorPageInfo, type Report, type ReportResult, type View, type ViewItem, type ViewResult, } from './client.js';
 /**
  * Container for an event with associated metadata.
  * @deprecated Will be generated from Rust

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAI9E,cAAc,aAAa,CAAA;AAG3B,YAAY,EAAE,QAAQ,EAAE,CAAA;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GACvD,MAAM,CAOR;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAA;AAEnD;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAA;AAEhC;;;GAGG;AACH,eAAO,MAAM,QAAQ,wDAMX,CAAA;AAEV;;;GAGG;AAIH,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AAMpB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,EAAE,CAAA;IACN,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,qBAAoB;IAC3C,QAAQ,CAAC,OAAO,qBAAoB;IACpC,MAAM,CAAC,QAAQ,CAAC,aAAa,oBAAmB;IAChD,QAAQ,CAAC,aAAa,oBAAmB;IACzC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAElE,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAG,MAAM,cAAc,EAAE,CAAA;gBAE1B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAG3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9E,cAAc,aAAa,CAAA;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,cAAc,EACd,KAAK,oBAAoB,EACzB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,QAAQ,EAAE,CAAA;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GACvD,MAAM,CAOR;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAA;AAEnD;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAA;AAEhC;;;GAGG;AACH,eAAO,MAAM,QAAQ,wDAMX,CAAA;AAEV;;;GAGG;AAIH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,gBAAgB,EAChB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,IAAI,EACT,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,aAAa,CAAA;AAMpB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,EAAE,CAAA;IACN,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,qBAAoB;IAC3C,QAAQ,CAAC,OAAO,qBAAoB;IACpC,MAAM,CAAC,QAAQ,CAAC,aAAa,oBAAmB;IAChD,QAAQ,CAAC,aAAa,oBAAmB;IACzC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAElE,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAG,MAAM,cAAc,EAAE,CAAA;gBAE1B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAG3D"}

package/dist/index.js

@@ -7,6 +7,8 @@
 // Re-export all Rust-generated types from ./generated
 // This includes the ID type alias (ID = string)
 export * from './generated';
+export { bindGraph, } from './graph-client.js';
+export { applyCollectionDiff, LiveCollection, LiveIndex, } from './live-collection.js';
 /**
  * Get the item type name from an entity type or query class.
  *

package/dist/live-collection.d.ts

@@ -0,0 +1,94 @@
+export type Identified = {
+    id: string;
+};
+export type LiveCollectionStatus = 'loading' | 'live' | 'error';
+export type CollectionDiff<T> = {
+    sequence: bigint;
+    deletes: readonly string[];
+    upserts: readonly T[];
+};
+export type CollectionChanges<T> = {
+    sequence: bigint | null;
+    reset: boolean;
+    deletes: readonly string[];
+    upserts: readonly T[];
+};
+export interface MutableKeyedCollection<T> {
+    clear(): void;
+    delete(id: string): boolean;
+    set(id: string, item: T): unknown;
+}
+/** Apply a Myko collection diff to any Map-compatible reactive collection. */
+export declare function applyCollectionDiff<T extends Identified>(target: MutableKeyedCollection<T>, diff: CollectionDiff<T>): CollectionChanges<T>;
+/**
+ * Stable, read-only keyed state for a live query or view.
+ *
+ * Diffs update the backing map in O(changes). Array materialization is lazy and
+ * memoized per revision, so row-oriented consumers never pay an O(result size)
+ * cost for an unrelated one-row update.
+ */
+export declare class LiveCollection<T extends Identified> {
+    #private;
+    get items(): ReadonlyMap<string, T>;
+    get size(): number;
+    get status(): LiveCollectionStatus;
+    get resolved(): boolean;
+    get error(): Error | undefined;
+    get sequence(): bigint | null;
+    /** Monotonically increases for every diff or terminal error notification. */
+    get revision(): number;
+    /** The latest incremental change, suitable for framework-native adapters. */
+    get changes(): CollectionChanges<T>;
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    /**
+     * Subscribe to one keyed item in O(1).
+     *
+     * Only an initial authoritative snapshot, an upsert/delete of this ID, or a
+     * later sequence-zero reset invokes the listener. This is the low-level
+     * primitive used by fine-grained client and graph watchers.
+     */
+    subscribeItem(id: string, listener: (item: T | undefined) => void): () => void;
+    /** Subscribe to cardinality changes without observing unrelated row updates. */
+    subscribeSize(listener: (size: number) => void): () => void;
+    entries(): IterableIterator<[string, T]>;
+    /** Lazily materialize a stable array for the current revision. */
+    toArray(): readonly T[];
+    apply(diff: CollectionDiff<T>): this;
+    fail(error: unknown): this;
+}
+export type LiveIndexChanges<K> = {
+    reset: boolean;
+    keys: readonly K[];
+};
+/**
+ * Stable incremental secondary index over a `LiveCollection`.
+ *
+ * The first update groups the current snapshot. Consecutive source revisions
+ * then touch only deleted and upserted items, using cached prior keys to move
+ * an item between buckets without scanning the source collection. If a caller
+ * skips revisions, `update` safely rebuilds from the authoritative source.
+ */
+export declare class LiveIndex<K, T extends Identified> {
+    #private;
+    constructor(keyOf: (item: T) => K);
+    get groups(): ReadonlyMap<K, ReadonlyMap<string, T>>;
+    get size(): number;
+    get status(): LiveCollectionStatus;
+    get resolved(): boolean;
+    get error(): Error | undefined;
+    get sequence(): bigint | null;
+    /** Increases once for every source revision incorporated by this index. */
+    get revision(): number;
+    /** Last incorporated `LiveCollection.revision`, or -1 before first update. */
+    get sourceRevision(): number;
+    /** Endpoint buckets affected by the latest incorporated source revision. */
+    get changes(): LiveIndexChanges<K>;
+    has(key: K): boolean;
+    /** A stable keyed bucket, or a shared immutable empty bucket. */
+    get(key: K): ReadonlyMap<string, T>;
+    /** Lazily materialize and memoize one bucket for the current revision. */
+    values(key: K): readonly T[];
+    update(source: LiveCollection<T>): this;
+}
+//# sourceMappingURL=live-collection.d.ts.map

package/dist/live-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-collection.d.ts","sourceRoot":"","sources":["../src/live-collection.ts"],"names":[],"mappings":"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"}

package/dist/live-collection.js

@@ -0,0 +1,302 @@
+const EMPTY_CHANGES = {
+    sequence: null,
+    reset: false,
+    deletes: [],
+    upserts: [],
+};
+/** Apply a Myko collection diff to any Map-compatible reactive collection. */
+export function applyCollectionDiff(target, diff) {
+    const reset = diff.sequence === 0n;
+    if (reset)
+        target.clear();
+    for (const id of diff.deletes)
+        target.delete(id);
+    for (const item of diff.upserts)
+        target.set(item.id, item);
+    return {
+        sequence: diff.sequence,
+        reset,
+        deletes: diff.deletes,
+        upserts: diff.upserts,
+    };
+}
+/**
+ * Stable, read-only keyed state for a live query or view.
+ *
+ * Diffs update the backing map in O(changes). Array materialization is lazy and
+ * memoized per revision, so row-oriented consumers never pay an O(result size)
+ * cost for an unrelated one-row update.
+ */
+export class LiveCollection {
+    #items = new Map();
+    #itemListeners = new Map();
+    #sizeListeners = new Set();
+    #array;
+    #status = 'loading';
+    #error;
+    #sequence = null;
+    #revision = 0;
+    #changes = EMPTY_CHANGES;
+    get items() {
+        return this.#items;
+    }
+    get size() {
+        return this.#items.size;
+    }
+    get status() {
+        return this.#status;
+    }
+    get resolved() {
+        return this.#sequence !== null;
+    }
+    get error() {
+        return this.#error;
+    }
+    get sequence() {
+        return this.#sequence;
+    }
+    /** Monotonically increases for every diff or terminal error notification. */
+    get revision() {
+        return this.#revision;
+    }
+    /** The latest incremental change, suitable for framework-native adapters. */
+    get changes() {
+        return this.#changes;
+    }
+    get(id) {
+        return this.#items.get(id);
+    }
+    has(id) {
+        return this.#items.has(id);
+    }
+    /**
+     * Subscribe to one keyed item in O(1).
+     *
+     * Only an initial authoritative snapshot, an upsert/delete of this ID, or a
+     * later sequence-zero reset invokes the listener. This is the low-level
+     * primitive used by fine-grained client and graph watchers.
+     */
+    subscribeItem(id, listener) {
+        let listeners = this.#itemListeners.get(id);
+        if (!listeners) {
+            listeners = new Set();
+            this.#itemListeners.set(id, listeners);
+        }
+        listeners.add(listener);
+        if (this.resolved)
+            listener(this.#items.get(id));
+        return () => {
+            const current = this.#itemListeners.get(id);
+            current?.delete(listener);
+            if (current?.size === 0)
+                this.#itemListeners.delete(id);
+        };
+    }
+    /** Subscribe to cardinality changes without observing unrelated row updates. */
+    subscribeSize(listener) {
+        this.#sizeListeners.add(listener);
+        if (this.resolved)
+            listener(this.#items.size);
+        return () => {
+            this.#sizeListeners.delete(listener);
+        };
+    }
+    entries() {
+        return this.#items.entries();
+    }
+    /** Lazily materialize a stable array for the current revision. */
+    toArray() {
+        this.#array ??= Array.from(this.#items.values());
+        return this.#array;
+    }
+    apply(diff) {
+        const wasResolved = this.resolved;
+        const previousSize = this.#items.size;
+        this.#changes = applyCollectionDiff(this.#items, diff);
+        this.#sequence = diff.sequence;
+        this.#status = 'live';
+        this.#error = undefined;
+        this.#revision += 1;
+        this.#array = undefined;
+        if (diff.sequence === 0n && this.#itemListeners.size > 0) {
+            for (const [id, listeners] of this.#itemListeners) {
+                const item = this.#items.get(id);
+                for (const listener of listeners)
+                    listener(item);
+            }
+        }
+        else if (this.#itemListeners.size > 0) {
+            const changedIds = new Set(diff.deletes);
+            for (const item of diff.upserts)
+                changedIds.add(item.id);
+            for (const id of changedIds) {
+                const listeners = this.#itemListeners.get(id);
+                if (!listeners)
+                    continue;
+                const item = this.#items.get(id);
+                for (const listener of listeners)
+                    listener(item);
+            }
+        }
+        if (this.#sizeListeners.size > 0 &&
+            (!wasResolved || previousSize !== this.#items.size)) {
+            for (const listener of this.#sizeListeners)
+                listener(this.#items.size);
+        }
+        return this;
+    }
+    fail(error) {
+        this.#status = 'error';
+        this.#error = error instanceof Error ? error : new Error(String(error));
+        this.#revision += 1;
+        this.#changes = EMPTY_CHANGES;
+        return this;
+    }
+}
+const EMPTY_GROUP = new Map();
+/**
+ * Stable incremental secondary index over a `LiveCollection`.
+ *
+ * The first update groups the current snapshot. Consecutive source revisions
+ * then touch only deleted and upserted items, using cached prior keys to move
+ * an item between buckets without scanning the source collection. If a caller
+ * skips revisions, `update` safely rebuilds from the authoritative source.
+ */
+export class LiveIndex {
+    #keyOf;
+    #groups = new Map();
+    #itemKeys = new Map();
+    #arrays = new Map();
+    #source;
+    #sourceRevision = -1;
+    #revision = 0;
+    #changes = { reset: false, keys: [] };
+    constructor(keyOf) {
+        this.#keyOf = keyOf;
+    }
+    get groups() {
+        return this.#groups;
+    }
+    get size() {
+        return this.#groups.size;
+    }
+    get status() {
+        return this.#source?.status ?? 'loading';
+    }
+    get resolved() {
+        return this.#source?.resolved ?? false;
+    }
+    get error() {
+        return this.#source?.error;
+    }
+    get sequence() {
+        return this.#source?.sequence ?? null;
+    }
+    /** Increases once for every source revision incorporated by this index. */
+    get revision() {
+        return this.#revision;
+    }
+    /** Last incorporated `LiveCollection.revision`, or -1 before first update. */
+    get sourceRevision() {
+        return this.#sourceRevision;
+    }
+    /** Endpoint buckets affected by the latest incorporated source revision. */
+    get changes() {
+        return this.#changes;
+    }
+    has(key) {
+        return this.#groups.has(key);
+    }
+    /** A stable keyed bucket, or a shared immutable empty bucket. */
+    get(key) {
+        return this.#groups.get(key) ?? EMPTY_GROUP;
+    }
+    /** Lazily materialize and memoize one bucket for the current revision. */
+    values(key) {
+        const cached = this.#arrays.get(key);
+        if (cached)
+            return cached;
+        const values = Array.from(this.get(key).values());
+        this.#arrays.set(key, values);
+        return values;
+    }
+    update(source) {
+        if (source.revision === this.#sourceRevision)
+            return this;
+        const changedKeys = new Set();
+        const consecutive = source.revision === this.#sourceRevision + 1;
+        if (this.#sourceRevision < 0 || !consecutive || source.changes.reset) {
+            for (const key of this.#groups.keys())
+                changedKeys.add(key);
+            this.#rebuild(source.items.values());
+            for (const key of this.#groups.keys())
+                changedKeys.add(key);
+            this.#changes = { reset: true, keys: Array.from(changedKeys) };
+        }
+        else {
+            for (const id of source.changes.deletes)
+                this.#remove(id, changedKeys);
+            for (const item of source.changes.upserts)
+                this.#upsert(item, changedKeys);
+            this.#changes = { reset: false, keys: Array.from(changedKeys) };
+        }
+        this.#source = source;
+        this.#sourceRevision = source.revision;
+        this.#revision += 1;
+        return this;
+    }
+    #rebuild(items) {
+        for (const group of this.#groups.values())
+            group.clear();
+        this.#groups.clear();
+        this.#itemKeys.clear();
+        this.#arrays.clear();
+        for (const item of items)
+            this.#insert(item);
+    }
+    #insert(item) {
+        const key = this.#keyOf(item);
+        this.#insertAt(key, item);
+    }
+    #insertAt(key, item) {
+        let group = this.#groups.get(key);
+        if (!group) {
+            group = new Map();
+            this.#groups.set(key, group);
+        }
+        group.set(item.id, item);
+        this.#itemKeys.set(item.id, key);
+        this.#arrays.delete(key);
+    }
+    #upsert(item, changedKeys) {
+        const key = this.#keyOf(item);
+        if (this.#itemKeys.has(item.id)) {
+            const previousKey = this.#itemKeys.get(item.id);
+            const previousGroup = this.#groups.get(previousKey);
+            // Comparing the resolved buckets uses the Map's SameValueZero key
+            // semantics and preserves a stable bucket when membership is unchanged.
+            if (previousGroup && previousGroup === this.#groups.get(key)) {
+                previousGroup.set(item.id, item);
+                this.#itemKeys.set(item.id, key);
+                this.#arrays.delete(previousKey);
+                changedKeys.add(previousKey);
+                return;
+            }
+            this.#remove(item.id, changedKeys);
+        }
+        this.#insertAt(key, item);
+        changedKeys.add(key);
+    }
+    #remove(id, changedKeys) {
+        if (!this.#itemKeys.has(id))
+            return;
+        const key = this.#itemKeys.get(id);
+        const group = this.#groups.get(key);
+        group?.delete(id);
+        this.#itemKeys.delete(id);
+        this.#arrays.delete(key);
+        changedKeys?.add(key);
+        if (group?.size === 0)
+            this.#groups.delete(key);
+    }
+}

package/package.json

@@ -37,11 +37,14 @@
     "url": "https://github.com/ignition-is-go/myko"
   },
   "scripts": {
+    "bench:command-routing": "bun benches/command-routing.ts",
+    "bench:live-collection": "bun benches/live-collection.ts",
+    "bench:selection": "bun benches/selection-routing.ts",
     "build": "tsc",
     "check": "tsc --noEmit --skipLibCheck",
-    "test": "echo 'no tests yet'"
+    "test": "bun test tests"
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "6.1.0"
+  "version": "6.3.0"
 }