@adobe/data 0.9.59 → 0.9.61

package/dist/ecs/database/public/create-database.js

@@ -3,6 +3,7 @@ import { Store } from "../../store/index.js";
 import { createReconcilingDatabase } from "../reconciling/create-reconciling-database.js";
 import { calculateSystemOrder } from "../calculate-system-order.js";
 import { createTransactionDispatcher } from "./create-transaction-dispatcher.js";
+import { observeSelectEntities } from "../observe-select-entities.js";
 /**
  * For each system in newDeclarations that is not yet in systemFunctions: call create(db),
  * store the returned value in systemFunctions, and assign by name. Uses natural declaration order.
@@ -63,6 +64,12 @@ function createEmptyDatabase(sync) {
     const services = {};
     const computed = {};
     const extendedPlugins = new Set();
+    // The Store layer owns the IndexRegistry: it instantiates the registry,
+    // maintains it eagerly on every insert/update/delete, and exposes the
+    // typed handle map as `store.indexes`. The Database layer just surfaces
+    // the same reference (via spread / explicit field below) so users see
+    // `db.indexes.<name>` and `t.indexes.<name>` pointing at one source of
+    // truth.
     const partialDatabase = {
         serviceName: "ecs-database-service",
         ...reconcilingDatabase,
@@ -71,10 +78,39 @@ function createEmptyDatabase(sync) {
         actions,
         services,
         computed,
+        indexes: store.indexes,
         store,
         system: { functions: systemFunctions, order: systemOrder },
         extend: undefined,
     };
+    // Auto-route `db.select(include, { where })` and `db.observe.select(...)`
+    // through a declared index when the where clause is exactly an equality
+    // match on the index's full key tuple and there is no order clause. Other
+    // shapes fall back to the archetype scan in the underlying store.
+    //
+    // The router dispatches through the user-visible handles in `store.indexes`
+    // so any override applied to the public handle — tests, instrumentation —
+    // takes effect for the routed path too.
+    const baseSelect = partialDatabase.select.bind(partialDatabase);
+    const indexAwareSelect = (include, options) => {
+        const routed = trySelectViaIndex(store, include, options);
+        if (routed !== null)
+            return routed;
+        return baseSelect(include, options);
+    };
+    partialDatabase.select = indexAwareSelect;
+    // `observeSelectEntities` reads from its `store` parameter via only
+    // `store.select` and `store.locate`. A minimal façade backed by the
+    // index-aware select + the real `store.locate` satisfies that contract,
+    // and replacing `observe.select` here mutates the shared `observe` object
+    // (same reference as `observedDatabase.observe`) before any user code
+    // can subscribe — so the default instance created inside
+    // `createObservedDatabase` is cleanly dropped, with no stale closures.
+    const indexAwareStoreFacade = {
+        select: indexAwareSelect,
+        locate: store.locate.bind(store),
+    };
+    partialDatabase.observe.select = observeSelectEntities(indexAwareStoreFacade, partialDatabase.observe.transactions);
     const extend = (plugin) => {
         if (!extendedPlugins.has(plugin)) {
             extendedPlugins.add(plugin);
@@ -93,6 +129,12 @@ function createEmptyDatabase(sync) {
                 if (!(name in computed))
                     computed[name] = pluginComputed[name](partialDatabase);
             }
+            // `reconcilingDatabase.extend(plugin)` above propagates down to
+            // `store.extend({ components, resources, archetypes, indexes })`,
+            // so the Store has already absorbed `plugin.indexes`. We refresh
+            // our local indexes reference in case the underlying map got a
+            // new identity (it doesn't today, but stay defensive).
+            partialDatabase.indexes = store.indexes;
             if (plugin.systems && Object.keys(plugin.systems).length > 0) {
                 Object.assign(allSystemDeclarations, plugin.systems);
                 systemOrder = calculateSystemOrder(allSystemDeclarations);
@@ -106,4 +148,108 @@ function createEmptyDatabase(sync) {
     partialDatabase.extend = extend;
     return partialDatabase;
 }
+/**
+ * Returns the equality value implied by `where[key]` if and only if the
+ * condition is a pure equality — either a direct primitive value or a
+ * comparison object with exactly `{ "==": v }`. Returns the sentinel
+ * `NOT_EQUALITY` when the condition uses any other operator.
+ */
+const NOT_EQUALITY = Symbol("not-equality");
+const equalityValue = (cond) => {
+    if (cond === null || typeof cond !== "object")
+        return cond;
+    const keys = Object.keys(cond);
+    if (keys.length === 1 && keys[0] === "==")
+        return cond["=="];
+    return NOT_EQUALITY;
+};
+/**
+ * Attempts to serve `select(include, options)` from a declared index.
+ *
+ * Returns `null` when no index applies; the caller must fall back to the
+ * archetype scan. Returns an `Entity[]` when an index can answer the query.
+ *
+ * Match conditions (intentionally conservative for V2):
+ *   - `options.where` is non-empty.
+ *   - `options.order` is absent (sort orders are routed in a follow-up).
+ *   - Every `where` key is a pure equality (`v` or `{ "==": v }`).
+ *   - The `where` keys, as a set, equal some index's `components`.
+ *
+ * The query planner accesses `store.indexes` (the user-visible handle map),
+ * so test spies and any future user-installed instrumentation see the call.
+ * Components for each index are recovered from the registry-internal handle
+ * (the handle exposes `find`/`findRange`/`get`; the column set is held by
+ * the underlying `RuntimeIndex`, which is the registry's source of truth).
+ * For the planner we treat the handle map structurally as
+ * `{ [name]: { findByValues, routableColumns } }` because Store internally
+ * augments each handle with these fields — see `createStore`.
+ *
+ * After the index lookup returns candidate entities, each candidate is
+ * checked for archetype membership of every `include` component so the
+ * returned set respects the same archetype filter as the scan path.
+ */
+function trySelectViaIndex(store, include, options) {
+    const where = options?.where;
+    if (!where || options?.order)
+        return null;
+    const whereKeys = Object.keys(where);
+    if (whereKeys.length === 0)
+        return null;
+    // Collapse where to an { component -> equality-value } record, bailing if
+    // any condition is not a pure equality.
+    const values = {};
+    for (const k of whereKeys) {
+        const eq = equalityValue(where[k]);
+        if (eq === NOT_EQUALITY)
+            return null;
+        values[k] = eq;
+    }
+    // Iterate the public handle map (store.indexes). Each handle carries a
+    // non-public `routableColumns` field placed by `createStore` for exactly
+    // this purpose. `routableColumns: null` opts an index out of raw-where
+    // auto-routing (function and slot-map keys live in a value space the
+    // planner cannot infer from a where clause).
+    //
+    // For a matched index the planner builds the appropriate `find`
+    // argument: a scalar for a single-column key, the full values object
+    // for a multi-column key. The call goes through `handle.find` so any
+    // user-installed spy or instrumentation on the handle sees the
+    // dispatch.
+    const handles = store.indexes;
+    let matchedHandle;
+    let matchedCols;
+    for (const name of Object.keys(handles)) {
+        const handle = handles[name];
+        const cols = handle.routableColumns;
+        if (cols === null)
+            continue;
+        if (cols.length !== whereKeys.length)
+            continue;
+        if (cols.every(c => c in values)) {
+            matchedHandle = handle;
+            matchedCols = cols;
+            break;
+        }
+    }
+    if (!matchedHandle || !matchedCols)
+        return null;
+    const findArg = matchedCols.length === 1 ? values[matchedCols[0]] : values;
+    const candidates = matchedHandle.find(findArg);
+    if (candidates.length === 0)
+        return [];
+    const includeArr = Array.from(include);
+    if (includeArr.length === 0)
+        return candidates.slice();
+    const result = [];
+    for (const entity of candidates) {
+        const location = store.locate(entity);
+        if (!location)
+            continue;
+        const cols = location.archetype.columns;
+        if (includeArr.every(c => cols[c] !== undefined)) {
+            result.push(entity);
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=create-database.js.map

package/dist/ecs/database/public/create-database.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-database.js","sourceRoot":"","sources":["../../../../src/ecs/database/public/create-database.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create-database.js","sourceRoot":"","sources":["../../../../src/ecs/database/public/create-database.ts"],"names":[],"mappings":"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"}

package/dist/ecs/database/transactional-store/transactional-store.d.ts

@@ -8,6 +8,7 @@ import { StringKeyof } from "../../../types/types.js";
 import { ArchetypeComponents } from "../../store/archetype-components.js";
 import { FromSchemas } from "../../../schema/from-schemas.js";
 import { Undoable } from "../undoable.js";
+import { IndexDeclarations } from "../../store/index-types.js";
 /**
  * The first argument passed to every transaction function. Extends the full
  * store read/write surface with `userId` — the identifier of the peer or user
@@ -17,10 +18,10 @@ import { Undoable } from "../undoable.js";
  *
  * `userId` is `undefined` in local-only (no-sync) databases.
  */
-export type TransactionContext<C extends Components, R extends ResourceComponents, A extends ArchetypeComponents<StringKeyof<C>>> = Store<C, R, A> & {
+export type TransactionContext<C extends Components, R extends ResourceComponents, A extends ArchetypeComponents<StringKeyof<C>>, IX extends IndexDeclarations<C> = {}> = Store<C, R, A, IX> & {
     readonly userId: number | string | undefined;
 };
-export interface TransactionalStore<C extends Components = never, R extends ResourceComponents = never, A extends ArchetypeComponents<StringKeyof<C>> = never> extends ReadonlyStore<C, R, A> {
+export interface TransactionalStore<C extends Components = never, R extends ResourceComponents = never, A extends ArchetypeComponents<StringKeyof<C>> = never, IX extends IndexDeclarations<C> = {}> extends ReadonlyStore<C, R, A, IX> {
     /**
      * Execute a transaction on the store.
      * The transactionFunction must NOT directly mutate archetype rows as those changes would not be captured.

package/dist/ecs/plugins/scheduler/scheduler.d.ts

@@ -12,4 +12,5 @@ export declare const scheduler: {
     readonly actions: {};
     readonly services: {};
     readonly computed: {};
+    readonly indexes: {};
 };

package/dist/ecs/store/index-types.d.ts

@@ -0,0 +1,132 @@
+import { StringKeyof } from "../../types/types.js";
+import type { Entity } from "../entity/entity.js";
+import { Components } from "./components.js";
+/**
+ * If `T` is an array type, the element type; otherwise `T` unchanged.
+ *
+ * Multi-value indexes auto-fan-out array values into per-element bucket
+ * entries at insert time. The lookup methods therefore take the element
+ * type, not the array — a query like `find("joe")` against a
+ * `Task { assigned: string[] }` is exactly what users want, and an array
+ * as a single opaque key is virtually never useful (order-dependent, not
+ * a natural query shape).
+ */
+type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
+/**
+ * Per-slot extractor in a compound `key` declaration. Either:
+ * - a `StringKeyof<C>` — read the value of that column directly, or
+ * - a function — derive the slot's value from the index's read components.
+ */
+export type IndexKeySlot<C extends Components> = StringKeyof<C> | ((...args: any[]) => unknown);
+/**
+ * The four shapes a `key` declaration can take. Drives the `find` / `get`
+ * argument type via {@link FindArg}.
+ *
+ *  - `string` — read this one column. `find` takes a scalar.
+ *  - `readonly string[]` — read each of these columns. `find` takes
+ *    `{ col1: ..., col2: ... }` keyed by the column names themselves.
+ *  - `(...args) => Value` — derive the bucket key from the components.
+ *    `find` takes whatever the function returns (or its element type
+ *    when the return is an array — multi-value fan-out).
+ *  - slot map — name each part of a compound key; values are either
+ *    column-name strings (identity) or extractor functions. `find`
+ *    takes an object keyed by the slot names.
+ */
+export type IndexKey<C extends Components> = StringKeyof<C> | readonly StringKeyof<C>[] | ((...args: any[]) => unknown) | {
+    readonly [slot: string]: IndexKeySlot<C>;
+};
+/**
+ * Within-bucket ordering. `by` declares the columns to read into the
+ * per-entity sort cache; `compare` (optional) is the comparator over
+ * `Pick<C, by[number]>`. When `compare` is omitted, the default is
+ * ascending across `by` from left to right with positional tie-break
+ * (`JS <` / `>` per column).
+ *
+ * `compare` is method shorthand for the same `IX & XIX` variance reason
+ * that `compute` was previously: `Store.extend`'s result intersects index
+ * declarations, which would otherwise trip `strictFunctionTypes` over
+ * contravariant parameter positions.
+ */
+export type IndexOrder<C extends Components, By extends readonly StringKeyof<C>[] = readonly StringKeyof<C>[]> = {
+    readonly by: By;
+    compare?(a: Pick<C, By[number]>, b: Pick<C, By[number]>): number;
+};
+/**
+ * Type-level declaration of an index.
+ *
+ * - `key` is the only required field. Its shape drives the bucket layout
+ *   and the lookup argument type of `find` / `get` / `findRange`.
+ * - `order` (optional) maintains sorted iteration within each bucket.
+ * - `unique` (optional) — when true, at most one entity may hold each
+ *   bucket key; `get(arg)` is exposed and returns `Entity | null`.
+ * - `components` (optional) — names the columns extractor functions
+ *   read. Only needed when at least one function reads a column not
+ *   implied by a string-identity key entry.
+ *
+ * See `packages/data/src/ecs/README.md` for the full pattern catalogue.
+ */
+export type Index<C extends Components = any, K extends IndexKey<C> = IndexKey<C>, O extends IndexOrder<C, any> | undefined = IndexOrder<C, any> | undefined, U extends boolean = boolean> = {
+    readonly key: K;
+    readonly order?: O;
+    readonly unique?: U;
+    readonly components?: readonly StringKeyof<C>[];
+};
+/**
+ * Resolve a slot's contributed `find` field type. Strings are identity
+ * reads on the named column; functions yield their return type (element
+ * type if the return is an array).
+ */
+type SlotFindType<C extends Components, V> = V extends StringKeyof<C> ? ElementOf<C[V]> : V extends (...args: any[]) => infer R ? ElementOf<R> : never;
+/** Argument type of `find` / `get` derived from the `key` shape. */
+type FindArg<C extends Components, K> = K extends StringKeyof<C> ? ElementOf<C[K]> : K extends readonly StringKeyof<C>[] ? {
+    readonly [P in K[number]]: ElementOf<C[P]>;
+} : K extends (...args: any[]) => infer R ? ElementOf<R> : K extends Record<string, IndexKeySlot<C>> ? {
+    readonly [Slot in keyof K]: SlotFindType<C, K[Slot]>;
+} : never;
+/** Comparison-operator filter on a scalar bucket-key value. */
+type OperatorFilter<T> = {
+    readonly "=="?: T;
+    readonly "!="?: T;
+    readonly "<"?: T;
+    readonly "<="?: T;
+    readonly ">"?: T;
+    readonly ">="?: T;
+};
+/**
+ * `findRange` argument: each field of the find argument may be either an
+ * equality value or a `<,<=,>,>=,==,!=` operator filter. For scalar keys
+ * the entire argument may itself be an operator filter.
+ */
+type RangeArg<T> = T extends object ? {
+    readonly [P in keyof T]?: T[P] | OperatorFilter<T[P]>;
+} : T | OperatorFilter<T>;
+export declare namespace Index {
+    /** Public lookup handle exposed on `db.indexes.<name>` and `t.indexes.<name>`. */
+    type Handle<C extends Components, I extends Index<C, any, any, any>> = I extends Index<C, infer K, any, infer U> ? {
+        find(arg: FindArg<C, K>): readonly Entity[];
+        findRange(arg: RangeArg<FindArg<C, K>>): readonly Entity[];
+    } & (U extends true ? {
+        get(arg: FindArg<C, K>): Entity | null;
+    } : {}) : never;
+}
+/**
+ * Plugin-level / store-level map of indexes. Keys are user-chosen index
+ * names; values are `Index` declarations whose `key` references real
+ * columns of `C`.
+ *
+ * The structural shape is inlined (rather than `Index<C, any, any, any>`) so
+ * that the per-entry `key`/`order` fields are actually constrained at the
+ * declaration site. With `Index<C, any, any, any>` the wildcard `any`
+ * generics widen `key` past `IndexKey<C>`, so a typo like `{ key: "bogus" }`
+ * silently passes the constraint. Inlining `key: IndexKey<C>` here makes
+ * the typo a type error at the plugin descriptor.
+ */
+export type IndexDeclarations<C extends Components = any> = {
+    readonly [name: string]: {
+        readonly key: IndexKey<C>;
+        readonly order?: IndexOrder<C>;
+        readonly unique?: boolean;
+        readonly components?: readonly StringKeyof<C>[];
+    };
+};
+export {};

package/dist/ecs/store/index-types.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=index-types.js.map

package/dist/ecs/store/index-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-types.js","sourceRoot":"","sources":["../../../src/ecs/store/index-types.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/ecs/store/public/create-store.js

@@ -1,6 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { createCore } from "../core/create-core.js";
 import { selectEntities } from "../core/select-entities.js";
+import { createIndexRegistry, } from "../../database/index-registry/index.js";
 export function createStore(schema) {
     const schemaArg = schema;
     const hasSchemaShape = schemaArg &&
@@ -21,6 +22,96 @@ export function createStore(schema) {
     const archetypeComponentNames = {};
     const componentAndResourceSchemas = {};
     const core = createCore(componentAndResourceSchemas);
+    // Index registry. Owned at the Store layer because index state is
+    // *derived* from store data, and every mutation that needs to keep
+    // indexes in sync flows through Store methods (insert / update /
+    // delete). Higher layers (`db.indexes`, `t.indexes`) expose this same
+    // map by reference.
+    //
+    // The reader is only used for `applyUpdate` — the patch passed to
+    // `store.update` may omit components an index covers, so the registry
+    // re-reads the full record to recompute the key. Seeding goes through
+    // `seedIndexFromArchetypes` instead (see below).
+    const indexRegistry = createIndexRegistry((entity) => {
+        const values = core.read(entity);
+        if (!values)
+            return null;
+        // Strip `id` — it is never a useful index key.
+        const { id: _id, ...rest } = values;
+        return rest;
+    });
+    /**
+     * Populate an index from the archetypes whose component set is a
+     * superset of the index's `components`. Only those archetypes can
+     * possibly contribute — entities in any other archetype lack at
+     * least one of the indexed components, so they would never match
+     * `find` / `findRange` / `get` anyway.
+     *
+     * For each candidate archetype, the values record is built directly
+     * from the dense column buffers (no `store.read` / `locate`
+     * indirection) and handed to `idx.add` once per row.
+     */
+    const seedIndexFromArchetypes = (idx) => {
+        // `idx.readColumns` already includes both bucket-key columns and
+        // sort columns (the RuntimeIndex unifies them at creation time).
+        // `queryArchetypes` filters to only those archetypes carrying the
+        // full set — entities in any other archetype lack at least one
+        // component the index touches and would never produce a key.
+        const required = idx.readColumns;
+        if (required.length === 0)
+            return;
+        const archetypes = core.queryArchetypes(required);
+        for (const archetype of archetypes) {
+            const idCol = archetype.columns.id;
+            for (let row = 0; row < archetype.rowCount; row++) {
+                const values = {};
+                for (const c of required) {
+                    values[c] = archetype.columns[c].get(row);
+                }
+                idx.add(idCol.get(row), values);
+            }
+        }
+    };
+    // Public handle map keyed by user-chosen name. Each entry exposes
+    // find/findRange (always) and get (when the index is unique). Same
+    // object reference flows up via spread to the Database layer.
+    const indexHandles = {};
+    const exposeIndexHandle = (name, idx) => {
+        if (name in indexHandles)
+            return;
+        // Decide whether the auto-router can dispatch a raw-equality `where`
+        // clause to this index. Routable iff the key declaration is a pure
+        // column reference (bare string) or column tuple (string array) —
+        // function keys derive a value from inputs (live in a different value
+        // space than the source columns) and slot maps name parts arbitrarily
+        // (`{ team: "team", role: ... }`), so the planner cannot infer the
+        // column set from a where clause alone for either.
+        const key = idx.key;
+        let routableColumns;
+        if (typeof key === "string") {
+            routableColumns = [key];
+        }
+        else if (Array.isArray(key)) {
+            routableColumns = key;
+        }
+        else {
+            routableColumns = null;
+        }
+        const handle = {
+            find: idx.find,
+            findRange: idx.findRange,
+            // Internal planner-only field. Not part of the public
+            // `Database.Index.Handle` type. `routableColumns: null` opts the
+            // index out of raw-where auto-routing (function/slot-map keys).
+            // The planner reads this to pick a matching index and then
+            // calls `handle.find` (so user-installed spies on the handle
+            // intercept the routed call).
+            routableColumns,
+        };
+        if (idx.unique)
+            handle.get = idx.get;
+        indexHandles[name] = handle;
+    };
     // Each resource will be stored as the only entity in an archetype of [id, <resourceName>]
     // The resource component we added above will contain the resource value
     const ensureResourceInitialized = (name, resourceSchema) => {
@@ -34,6 +125,9 @@ export function createStore(schema) {
             const insertValues = isEphemeral
                 ? { [resourceId]: resourceSchema.default, ephemeral: true }
                 : { [resourceId]: resourceSchema.default };
+            // Resource singleton inserts bypass index pre-check because
+            // resources are not typically indexed by their schema name and
+            // the singleton row is created exactly once.
             archetype.insert(insertValues);
         }
         if (!Object.prototype.hasOwnProperty.call(resources, name)) {
@@ -52,8 +146,66 @@ export function createStore(schema) {
         return selectEntities(core, include, options);
     };
     const archetypes = {};
+    /**
+     * Wraps a raw Core archetype so `insert` maintains index state. Pre-checks
+     * unique constraints *before* the column mutation so a collision throws
+     * without partially mutating the store. Other archetype methods are
+     * passed through unchanged via the Proxy.
+     *
+     * Cached by raw archetype identity so repeated lookups
+     * (`store.archetypes.X`, `store.ensureArchetype([...])`) all return the
+     * same wrapper reference — code that uses `===` to compare archetypes
+     * keeps working.
+     */
+    const archetypeWrapCache = new WeakMap();
+    const wrapArchetypeForIndexes = (archetype) => {
+        const cached = archetypeWrapCache.get(archetype);
+        if (cached)
+            return cached;
+        const rawInsert = archetype.insert.bind(archetype);
+        const wrappedInsert = (values) => {
+            indexRegistry.checkUniqueAvailableForInsert(values);
+            const entity = rawInsert(values);
+            indexRegistry.applyInsert(entity, values);
+            return entity;
+        };
+        const wrapped = new Proxy(archetype, {
+            get(target, prop, receiver) {
+                if (prop === "insert")
+                    return wrappedInsert;
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+        archetypeWrapCache.set(archetype, wrapped);
+        return wrapped;
+    };
+    const ensureArchetype = ((componentNames) => {
+        return wrapArchetypeForIndexes(core.ensureArchetype(componentNames));
+    });
+    // `queryArchetypes` and `locate` also surface archetypes — wrap them
+    // so `===` comparisons against `store.archetypes.X` continue to hold.
+    // Cached wrappers guarantee identity stability per raw archetype.
+    const queryArchetypes = ((include, options) => {
+        const raw = core.queryArchetypes(include, options);
+        return raw.map((a) => wrapArchetypeForIndexes(a));
+    });
+    const locate = ((entity) => {
+        const loc = core.locate(entity);
+        if (loc === null)
+            return null;
+        return { archetype: wrapArchetypeForIndexes(loc.archetype), row: loc.row };
+    });
+    const updateEntity = (entity, values) => {
+        indexRegistry.checkUniqueAvailableForUpdate(entity, values);
+        core.update(entity, values);
+        indexRegistry.applyUpdate(entity);
+    };
+    const deleteEntity = (entity) => {
+        core.delete(entity);
+        indexRegistry.applyDelete(entity);
+    };
     const extend = (schema) => {
-        const { components: schemaComponents = {}, resources: schemaResources = {}, archetypes: schemaArchetypes = {} } = schema;
+        const { components: schemaComponents = {}, resources: schemaResources = {}, archetypes: schemaArchetypes = {}, indexes: schemaIndexes = {}, } = schema;
         // components: existing must be identical if present
         for (const [name, newComponentSchema] of Object.entries(schemaComponents)) {
             if (name in componentAndResourceSchemas) {
@@ -81,7 +233,8 @@ export function createStore(schema) {
             newResourceNames.push(name);
             ensureResourceInitialized(name, newResourceSchema);
         }
-        // archetypes: existing must be identical if present
+        // archetypes: existing must be identical if present.
+        // Wrap each archetype with index maintenance hooks at exposure time.
         for (const [name, newComponents] of Object.entries(schemaArchetypes)) {
             if (name in archetypeComponentNames) {
                 if (archetypeComponentNames[name] !== newComponents) {
@@ -91,21 +244,48 @@ export function createStore(schema) {
             }
             archetypeComponentNames[name] = newComponents;
             const archetype = core.ensureArchetype(["id", ...newComponents]);
-            archetypes[name] = archetype;
+            archetypes[name] = wrapArchetypeForIndexes(archetype);
+        }
+        // indexes: registry enforces (===)-or-throw on same name and
+        // structural duplicate detection across names. A new RuntimeIndex
+        // is returned when registration actually happened (vs. a benign
+        // identity-match re-register), in which case we seed it from the
+        // archetypes that contain its component set — and only those.
+        const declaredIndexes = schemaIndexes;
+        for (const name in declaredIndexes) {
+            const newIdx = indexRegistry.register(name, declaredIndexes[name]);
+            if (newIdx) {
+                exposeIndexHandle(name, newIdx);
+                seedIndexFromArchetypes(newIdx);
+            }
         }
         return store;
     };
     const store = {
         ...core,
+        ensureArchetype,
+        queryArchetypes,
+        locate,
+        update: updateEntity,
+        delete: deleteEntity,
         resources,
         select,
         archetypes,
+        indexes: indexHandles,
         extend,
         reset: () => {
             core.reset();
             for (const [name, resourceSchema] of Object.entries(resourceSchemas)) {
                 ensureResourceInitialized(name, resourceSchema);
             }
+            // After reset, every index bucket is wiped. Resources are the
+            // only entities that exist post-reset; seed each index from
+            // archetypes so resource singletons whose components an index
+            // happens to cover still appear.
+            indexRegistry.clear();
+            for (const idx of indexRegistry.indexes.values()) {
+                seedIndexFromArchetypes(idx);
+            }
         },
         toData: () => core.toData(),
         fromData: (data) => {
@@ -113,6 +293,12 @@ export function createStore(schema) {
             for (const [name, resourceSchema] of Object.entries(resourceSchemas)) {
                 ensureResourceInitialized(name, resourceSchema);
             }
+            // The loaded core has all entities; re-derive each index by
+            // walking only the archetypes that contain its components.
+            indexRegistry.clear();
+            for (const idx of indexRegistry.indexes.values()) {
+                seedIndexFromArchetypes(idx);
+            }
         },
     };
     return store.extend(normalizedSchema);