@oasys/oecs 0.5.3 → 0.6.0

package/dist/core/ecs/store.d.ts

@@ -1,66 +1,30 @@
 import { EntityID } from './entity.js';
+import { AccessorColumns, CursorBinder, SparseCursorCheck } from './ref.js';
 import { FrameTraceSink } from './frame_trace.js';
 import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component.js';
-import { SparseComponentDef, SparseComponentID } from './sparse_store.js';
-import { RelationDef, RelationOptions } from './relation.js';
-import { EmptyEventSchema, EventDef, EventReader, EventShape } from './event.js';
+import { SparseComponentStore, SparseComponentDef, SparseComponentID } from './sparse_store.js';
+import { RelationDef, RelationHooks, RelationServiceHost } from './relation.js';
+import { EventHooks } from './event.js';
+import { ResourceRegistry } from './resource_registry.js';
 import { BitSet, TypedArrayTag } from '../../type_primitives/index.js';
 import { Archetype, ArchetypeID } from './archetype.js';
-import { Query, QueryHost } from './query.js';
+import { Query } from './query.js';
+import { QueryHost } from './query_cache.js';
+import { QueryTerms } from './query_terms.js';
+import { DrainResult, ObservationFlags, StructuralObserverEvents, Template } from './store_types.js';
 import { ObserverHost } from './observer.js';
+import { ChangeFeed } from './change_feed.js';
+import { EntityAllocator } from './entity_allocator.js';
+import { SnapshotHooks, SnapshotHost } from './snapshot.js';
 import { InPlaceBufferAllocator, ColumnStoreRegionHandle, StoreRegionSpec, ColumnStore } from '../store/index.js';
 import { ECSMemoryCapContext } from './ecs_memory.js';
-export interface ComponentMeta {
-    /** Optional debug name from `registerComponent(schema, { name })` —
-     * diagnostic messages only, never behaviour. */
-    name?: string;
-    fieldNames: string[];
-    fieldIndex: Record<string, number>;
-    fieldTypes: TypedArrayTag[];
-    /** Has an onAdd observer — collect effective adds for this component. */
-    obsAdd: boolean;
-    /** Has an onRemove observer — collect effective removes for this component. */
-    obsRem: boolean;
-    /** Has an onDisable observer (#677) — collect effective disables for this
-     * component at the toggle drain. */
-    obsDisable: boolean;
-    /** Has an onEnable observer (#677) — collect effective enables for this
-     * component at the toggle drain. */
-    obsEnable: boolean;
-    /** Has a per-entity onSet observer — record dirty rows on the write path
-     * (the ADR-0012 opt-in dirty list). */
-    trackDirty: boolean;
-}
-/**
- * Effective `(component, entity)` structural events for one fixed-point round,
- * collected during `_flushAdds` / `_flushRemoves` and handed to the observer
- * dispatch hook. Flat parallel arrays, count-bounded (`*_len`), reused across
- * rounds — never reallocated in the flush. This is a scheduling artifact: it is
- * NOT part of `stateHash` or snapshot. See `observer.ts`.
- */
-export interface StructuralObserverEvents {
-    addComp: number[];
-    addEid: number[];
-    addLen: number;
-    remComp: number[];
-    remEid: number[];
-    remLen: number;
-    /** Effective disable events (#677) — collected during the toggle drain
-     * (`_flushToggles`), one per `(component, entity)` of each net-disabled
-     * entity's mask. Empty on a structural (add/remove/destroy) round. */
-    disComp: number[];
-    disEid: number[];
-    disLen: number;
-    /** Effective enable events (#677), symmetric with the disable arrays. */
-    enaComp: number[];
-    enaEid: number[];
-    enaLen: number;
-}
-/** Runtime shape of one template / `addComponents` entry: a def plus optional
- * field values (omitted fields zero-fill). The public authoring surface is
- * callable-bundle varargs, schema-checked per item by `StrictBundles`
- * (component.ts); the `ECS` facade normalizes those bundles into this erased
- * array before calling the store, so the store stays schema-agnostic. */
+export type { ComponentMeta, DrainResult, ObservationFlags, StructuralObserverEvents, Template } from './store_types.js';
+/** Runtime shape of one template entry or `addComponents` entry: a def plus
+ * optional field values (an omitted field zero-fills). The public authoring
+ * surface is callable-bundle varargs, schema-checked for each item by
+ * `StrictBundles` in `component.ts`. The `ECS` facade normalizes those bundles
+ * into this erased array before it calls the store, so the store stays
+ * schema-agnostic. */
 type TemplateEntryData = {
     readonly def: ComponentDef;
     readonly values?: Readonly<Record<string, number>>;
@@ -74,201 +38,259 @@ type TemplateFieldNames<Defs extends readonly ComponentDef[]> = Defs[number] ext
 export type TemplateOverrides<Defs extends readonly ComponentDef[]> = {
     readonly [K in TemplateFieldNames<Defs>]?: number;
 };
-declare const __templateDefs: unique symbol;
-/** A resolved template (#462) — an archetype template produced by
- * `ECS.template(...)`. **Opaque** apart from `defs`: callers hold it and pass
- * it to `ECS.spawn` / `ECS.spawnMany` (and may reference it in a system's
- * `spawns` / `despawns` access declaration — the scheduler expands it to
- * `defs`); the remaining fields are engine-internal and may change. `spawn`
- * lands an entity directly in `archetype_id` with zero archetype transitions,
- * writing `flatValues` (defaults in `_flatColumns` order) in one append
- * pass. See ADR-0010. */
-export interface Template<Defs extends readonly ComponentDef[] = readonly ComponentDef[]> {
-    readonly archetypeId: ArchetypeID;
-    readonly flatValues: number[];
-    readonly overrideIndex: Map<string, number>;
-    /** The component set this template spawns into, in entry order. */
-    readonly defs: readonly ComponentDef[];
-    readonly [__templateDefs]?: Defs;
-}
 export interface StoreOptions {
     initialCapacity?: number;
     /** Pluggable SAB buffer source. When provided, `createColumnStore`,
      * `extendColumnStore`, and `growColumnStore` route through it. Default is
-     * `growableSabAllocator()`. Typed `InPlaceBufferAllocator` (#682): a live
+     * `growableSabAllocator`. Typed `InPlaceBufferAllocator`: a live
      * Store's flush loops hoist entity-index views across grows, so only
-     * in-place allocators may back one (ADR-0008) — the constructor also
+     * in-place allocators may back one, the constructor also
      * runtime-asserts the marker for untyped JS callers. Consumers normally
-     * don't touch this directly; `ECSOptions.memory` resolves to it. */
+     * don't touch this directly. `ECSOptions.memory` resolves to it. */
     bufferAllocator?: InPlaceBufferAllocator;
-    /** Sizing intent the world was constructed with (#682), used to phrase
+    /** Sizing intent the world was constructed with, used to phrase
      * allocator-cap and entity-index-overflow errors in the caller's own
-     * terms ("3.2× the declared budget") instead of raw bytes. Wired by
-     * `ECS` from `resolveECSMemory`; absent for bare test Stores. */
+     * terms (a multiple of the declared budget) instead of raw bytes. Wired by
+     * `ECS` from `resolveECSMemory`. Absent for bare test Stores. */
     capContext?: ECSMemoryCapContext;
     /** Fired after every SAB resize (extend or grow). The new SAB has
      * already been built and archetypes have already refreshed their
-     * views by the time this fires. Used by ECS to call
-     * `sim.setLayout(0)` so WASM-side cached pointers re-walk. */
-    onBufferResized?: () => void;
-    /** Max live entities the SAB entity-index region holds (#245 / PR 4B).
-     * Default `ENTITY_INDEX_DEFAULT_CAPACITY` (`1 << 20` — the full EntityID
+     * views by the time this fires. `ECS` uses it to call `setLayout` on every
+     * subscribed layout listener, so a WASM-side cached pointer re-walks. */
+    onBufferReplaced?: () => void;
+    /** Max live entities the SAB entity-index region holds.
+     * Default `ENTITY_INDEX_DEFAULT_CAPACITY` (`1 << 20`, the full EntityID
      * index space). Exceeding this at runtime throws `EID_MAX_INDEX_OVERFLOW`.
-     * Tests with small entity counts may set lower to bench the SAB region size
-     * or to make index exhaustion reachable; a 1000-entity workload fits
-     * comfortably in the default. */
+     * Tests with small entity counts may set lower to shrink the SAB region or
+     * to make index exhaustion reachable. */
     entityIndexCapacity?: number;
-    /** Consumer-declared SAB regions (#623), forwarded verbatim to
+    /** Byte offset inside the backing where the store header goes. Default 0.
+     * Forwarded verbatim to `createColumnStore`, and every offset in the bytes
+     * is relative to it. `ECSOptions.memory.storeBase` resolves to it. */
+    storeBase?: number;
+    /** Consumer-declared SAB regions, forwarded verbatim to
      * `createColumnStore`. Each `StoreRegionSpec` carries an opaque `region_id`,
-     * a precomputed byte size, and an `init` closure; the engine lays them out
-     * generically and exposes them via `regionHandle(id)` / `regionOffset(id)`.
-     * A game (e.g. `@internal/sim`'s region specs) supplies these — the engine
-     * ships no game regions of its own. Omitted ⇒ none. */
+     * a precomputed byte size, and an `init` closure. The engine lays them out
+     * generically and exposes them through `regionHandle(id)` and
+     * `regionOffset(id)`. A consumer supplies the specs. The engine ships no
+     * region of its own. Omitted ⇒ none. */
     regions?: readonly StoreRegionSpec[];
-    /** Byte size of the opt-in sim-bindings region (#625), forwarded verbatim to
+    /** Byte size of the opt-in sim-bindings region, forwarded verbatim to
      * `createColumnStore`. A consumer that attaches a WASM backend passes its own
-     * size (`@internal/sim`'s `SIM_BINDINGS_BYTES`, computed from the binding
-     * manifest); the host then writes the `(component_id, field_id)` IDs into the
-     * region. Omitted / 0 ⇒ no region (a pure-TS game pays nothing for the WASM
-     * seam). De-welded from the engine ABI in #625 so a manifest edit doesn't
-     * drift an engine golden. */
+     * size, computed from its own binding manifest. The host then writes the
+     * `(component_id, field_id)` ids into the region. Omitted or 0 ⇒ no region,
+     * so a pure-TS world pays nothing for the WASM seam. The size stays out of
+     * the engine ABI, so a manifest edit does not drift an engine golden. */
     bindingsRegionBytes?: number;
-    /** Opt into the **determinism surface** (#626 / ADR-0020). Default `false`.
-     * Gates the three methods that fold/serialize state in canonical (sorted)
+    /** Opt into the **determinism surface**. Default `false`.
+     * Gates the three methods that fold and serialize state in canonical (sorted)
      * order: `stateHash`, `snapshotSparse`, `restoreSparse`. When `false`
-     * those throw `DETERMINISM_DISABLED` — the canonical-ordering tax (sparse
+     * those throw `DETERMINISM_DISABLED`, the canonical-ordering tax (sparse
      * `canonicalIndices` sort + relation target-set sort) is never paid, and a
      * consumer can't accidentally read a non-canonical digest. When `true`,
-     * today's behavior is reproduced bit-for-bit. This is the ONLY effect of the
+     * today's behavior is reproduced bit-for-bit. This is the only effect of the
      * flag: it does not touch the per-tick path, the in-place-allocator invariant
-     * (ADR-0008, a memory-safety requirement that holds regardless), or the
+     * (a memory-safety requirement that holds regardless), or the
      * always-on `enabled_count` partition maintenance. The flag's value is a
-     * capability gate, not a hot-path switch — `stateHash`/snapshot are never
-     * called per tick. */
+     * plugin gate, not a hot-path switch. `stateHash` and the snapshot are
+     * never called per tick. */
     deterministic?: boolean;
 }
-export declare class Store implements ObserverHost, QueryHost {
-    private readonly entityAllocator;
-    private readonly componentMetas;
-    private componentCount;
-    private readonly sparseStores;
-    /** Debug names parallel to `sparseStores` — diagnostics only. */
-    private readonly sparseNames;
-    private readonly relationService;
-    private readonly events;
-    private readonly archGraph;
-    private readonly registeredQueries;
-    private emptyArchetypeId;
-    private entityArchetype;
-    private entityRow;
+export declare class Store implements ChangeFeed, ObserverHost, QueryHost {
+    private readonly _entityAllocator;
+    private readonly _componentMetas;
+    private readonly _sparseStores;
+    /** Debug names parallel to `_sparseStores`, diagnostics only. */
+    private readonly _sparseNames;
+    /** The reused result of `drainSparseSet`, parallel to `_sparseStores`,
+     * allocated for a sparse component with an entity-level onSet. */
+    private readonly _sparseDrains;
+    private _relations;
+    private _events;
+    private readonly _archGraph;
+    private _emptyArchetypeId;
+    private _entityArchetypes;
+    private _entityRows;
+    private readonly _queries;
     private readonly _deferred;
-    private readonly _snapshots;
-    _tick: number;
-    /** Per-world frame-trace sink (ADR-0030), installed via `ECS.setTrace`.
+    private _snapshots;
+    get relations(): RelationHooks;
+    /** The relation service, for a caller that is not `ecs.relations`.
+     *
+     * The getter above names `ecs.relations` in its fault. That is the wrong
+     * remedy when a system context or a query term reached the service. Every
+     * seam a user can reach passes its own name here. Error path only. The
+     * successful read is the same field read the getter makes. */
+    requireRelations(api: string): RelationHooks;
+    /** Build the host the relation service needs. Closures, not field
+     * references: `generations`, `entityArchetypes` and `entityRows` are
+     * reallocated when capacity grows, so each accessor re-reads the live
+     * field. */
+    relationHost(): RelationServiceHost;
+    /** Install the relations plugin. Called once, by the plugin. */
+    installRelations(service: RelationHooks): void;
+    get events(): EventHooks;
+    /** The event registry, for a caller that is not `ecs.events`. Names the
+     * seam the user reached, the way `requireRelations` does. */
+    requireEvents(api: string): EventHooks;
+    /** Whether the events plugin is installed. Read once per frame by the
+     * tick-tail clear, which must be a no-op on a world without channels. */
+    get hasEvents(): boolean;
+    /** Install the events plugin. Called once, by the plugin. */
+    installEvents(registry: EventHooks): void;
+    /** Build the host a snapshot plugin needs. Only the store can reach
+     * these fields, so it builds the record and the plugin owns the service.
+     * The accessors re-read live fields per call: the column store and the
+     * entity-index views are replaced on a restore. All cold path. */
+    snapshotHost(): SnapshotHost;
+    /** The allocator, which is its own snapshot seam. Handed to the plugin
+     * so the store need not construct the service itself. */
+    get entityAllocator(): EntityAllocator;
+    /** Install the snapshot plugin. Called once, by the plugin. */
+    installSnapshots(service: SnapshotHooks): void;
+    get snapshots(): SnapshotHooks;
+    get resources(): ResourceRegistry;
+    tick: number;
+    /** The change tick. A monotonic counter that the schedule advances before
+     * each system run, before each phase flush, before the onSet dispatch and
+     * at the end of each update. Every write stamps it on the archetype column
+     * it touches, and a consumer compares against the value of its own last
+     * run. The frame tick above cannot order a writer and a reader inside one
+     * frame, so a write by an earlier system was reported on two frames. This
+     * counter orders them. It starts above the initial column stamp, so the
+     * first run of a system sees every row that exists. A scheduling artifact:
+     * not in `stateHash` or the snapshot, and monotonic across a restore. */
+    changeTick: number;
+    /** Advance the change tick and return the new value, the stamp for the
+     * run that follows. Hot path: one increment per system run. */
+    advanceChangeTick(): number;
+    /** Per-world frame-trace sink, installed via `ECS.setTrace`.
      * `null` unless a consumer attaches a recorder. Every call site is
-     * `if (DEV) store._trace?.…`, so production builds dead-code-eliminate
-     * the seam and pay only this one nullable field. The sink observes; it never
-     * folds into `stateHash` (a scheduling artifact, like `_changedTick` / the
-     * observer state below). */
-    _trace: FrameTraceSink | null;
+     * `if (DEV) store.trace?.…`, so production builds dead-code-eliminate
+     * the seam and pay only this one nullable field. The sink observes. It never
+     * folds into `stateHash`. It is a scheduling artifact, like `_changedTick`
+     * and like the observer state below. */
+    trace: FrameTraceSink | null;
     private _structuralObserverCount;
-    /** Count of components with any onDisable/onEnable observer (#677). While 0
+    /** Count of components with any onDisable and onEnable observer. While 0
      * (with `_structuralObserverCount` also 0), `flushStructural` takes the
      * byte-for-byte fast path and the toggle drain skips event collection. */
     private _toggleObserverCount;
+    /** One flag record for each consumer of the change feed, keyed by the
+     * plugin name, each array indexed by component id and sparse. The
+     * store merges by OR across the records, so the flags a component carries
+     * are the union of what every consumer asked for. Cold: written when a
+     * consumer gains or loses an observer, read on the same call. */
+    private readonly _observationFlags;
+    /** The sparse half of the record above, one boolean for each sparse
+     * component a consumer wants the entity grain of. */
+    private readonly _sparseObservationFlags;
     /** Reused effective-event scratch for the current flush round. */
     private readonly _obsEvents;
-    /** Installed via `setStructuralObserverHook` — dispatches a round's collected
-     * events to the observer registry (ordering + callbacks), which may enqueue
-     * further structural ops. */
-    private _structuralObserverHook;
-    /** Install the structural-observer dispatch hook (called once by `ECS`
-     * during construction) — the named seam replacing direct writes to the
-     * previously-public field (M1). */
-    setStructuralObserverHook(fn: (ev: StructuralObserverEvents) => void): void;
+    /** Installed via `addStructuralHook`, each one dispatches a round's
+     * collected events to one consumer of the change feed, which may enqueue
+     * further structural ops. Empty on a world that installed no consumer, and
+     * the flush reads it once per round. */
+    private readonly _structuralHooks;
+    /** Add a consumer of the structural event batches. Each round of the
+     * observed flush hands its effective events to every hook, in install
+     * order. The events scratch is store-owned and reused, so a hook reads it
+     * during the call and copies whatever it keeps. Cold path. */
+    addStructuralHook(fn: (ev: StructuralObserverEvents) => void): void;
     private _collectDestroyEid;
     private readonly _collectDestroyRemoveBit;
     private _collectToggleEid;
     private readonly _collectDisableBit;
     private readonly _collectEnableBit;
-    /** Net-transition snapshot for the toggle drain (#677): entity → its disabled
-     * state at the START of the drain. Reused, cleared each drain. Lets
+    /** Net-transition snapshot for the toggle drain: entity → its disabled
+     * state at the start of the drain. Reused, cleared each drain. Lets
      * `_flushToggles` emit one event per *net* transition (disable→enable→disable
-     * within a tick = a single onDisable) instead of one per buffered op — required
+     * within a tick = a single onDisable) instead of one per buffered op, required
      * because the radix canonical-order pass would otherwise reorder duplicate eids
-     * and mis-sequence a consumer's delete/republish. */
+     * and mis-sequence a consumer's delete and republish. */
     private readonly _toggleInitial;
-    _anyDirtyTracked: boolean;
+    /** True once any component has row ticks. Gates the record at every write
+     * site, so a world without one pays a load and a branch there. */
+    anyDirtyTracked: boolean;
+    /** The components with row ticks, for the archetypes born later. */
     private readonly _dirtyTrackedCids;
     private readonly _dirtyLists;
-    private readonly _dirtyMarks;
+    private readonly _drainResults;
     /** Set by any path that changes a SAB-backed archetype's live row count
-     * (`flushStructural`/`flushDestroyed` when they did work; immediate
+     * (`flushStructural` and `flushDestroys` when they did work, immediate
      * `destroyEntity`, `addComponent(s)`, `removeComponent(s)` on the
-     * Store). Cleared by `publishRowCountsToDescriptor`. Lets read-only
-     * phases' `ctx.flush()` skip the descriptor walk entirely (#324). */
+     * Store). Cleared by `publishRowCounts`. Lets read-only
+     * phases' `ctx.flush` skip the descriptor walk entirely. */
     private _rowCountsDirty;
     /** Monotonic counter bumped by every membership-changing path (immediate
      * `addComponent(s)`, `removeComponent(s)`, `destroyEntity`,
      * `batchAddComponent`, `batchRemoveComponent`, `flushStructural`,
-     * `flushDestroyed`, and new-archetype installs in `ArchetypeGraph.install`).
-     * Read by `Query._nonEmpty()` via `QueryResolver._getQueryDirtyEpoch`
-     * — a query whose stored `_lastSeenEpoch` matches the current epoch
-     * reuses its cached non-empty list (#327). Replaces the previous walk
-     * over `registeredQueries` that wrote one dirty bit per query per
-     * mutation; 5000 startup adds × Q queries used to be 5000×Q writes,
-     * now it's 5000 integer increments. Public so ECS can forward through
-     * its `QueryResolver` impl; not part of the user-facing API. */
-    _queryDirtyEpoch: number;
-    private readonly initialCapacity;
-    private readonly _scratchTargetMask;
+     * `flushDestroys`, and new-archetype installs in `ArchetypeGraph.install`).
+     * Read by `Query.nonEmptyArchs()` via `QueryResolver.getQueryDirtyEpoch`.
+     * A query whose stored `_lastSeenEpoch` matches the current epoch
+     * reuses its cached non-empty list. Replaces the previous walk
+     * over `_registeredQueries` that wrote one dirty bit per query per
+     * mutation. A startup that adds many rows used to write one bit for each
+     * query at each mutation. Now it writes one integer increment. Public, so
+     * ECS can forward through its `QueryResolver` impl. It is not part of the
+     * user-facing API. */
+    queryDirtyEpoch: number;
     private _columnStore;
+    /** Row capacity every new archetype's columns start with. Taken from
+     * `StoreOptions.initialCapacity` at construction, read again by the
+     * archetype graph's `initialCapacity` host closure whenever it plants a
+     * new archetype. It sat under the row-grain banner, which owns the change
+     * detection state, and it sizes the backing instead. */
+    private readonly _initialCapacity;
     /** Installed on every SAB-backed Archetype so the Archetype can
      * request a SAB grow when an insertion would exceed its column
      * capacity. Doubles the offending archetype's row capacity (or jumps
      * to whatever fits `arch.length + additional`, whichever is larger),
      * reallocs the SAB via `growColumnStore` (live rows of every archetype
      * are carried forward), and republishes column views to every
-     * SAB-backed archetype. Plan §8.1 / §8.3 / §8.4. (#171 §6.1.9 Phase 3) */
+     * SAB-backed archetype. */
     private readonly _growHandler;
-    /** Build the intent-aware fatal for an allocator cap hit (#682). The
-     * allocator can only name raw bytes; the Store knows what the caller
+    /** Build the intent-aware fatal for an allocator cap hit. The
+     * allocator can only name raw bytes. The Store knows what the caller
      * declared (`capContext`) and how many entities are live, so the error
-     * says "3.2× the declared budget — runaway creation upstream?" instead
+     * names the live count as a multiple of the declared budget instead
      * of leaving the caller to reverse-engineer byte counts. Fatality is
-     * unchanged (#380: no grow-beyond-cap fallback). */
+     * unchanged (no grow-beyond-cap fallback). */
     private _capExceededError;
     private readonly _bufferAllocator;
     private readonly _capContext;
     private readonly _onBufferResized;
-    /** Construct with an `initialCapacity` number (legacy form) or an
-     * options object (new in PR 3D — adds `bufferAllocator` and
-     * `onBufferResized` callback). Both signatures coexist so test fixtures
+    /** Construct with an `_initialCapacity` number (legacy form) or an
+     * options object (adds `bufferAllocator` and
+     * `onBufferReplaced` callback). Both signatures coexist so test fixtures
      * that pass `new Store(4)` keep working. */
     constructor(arg?: number | StoreOptions);
     /** Capacity of the entity-index SAB region (max slots ≈ max live
-     * entities). Fixed at construction in #245's PR 4B scope; a future
+     * entities). Fixed at construction. A future
      * follow-up will grow it via `growColumnStore` when `entityHighWater`
      * hits the cap. */
     private readonly _entityIndexCapacity;
-    /** Consumer-declared SAB regions (#623), captured so the realloc path
+    /** Byte offset of the store header inside the backing. Fixed at
+     * construction, and every offset in the bytes is relative to it. */
+    private readonly _storeBase;
+    /** Consumer-declared SAB regions, captured so the realloc path
      * re-lays them out. `undefined` when no consumer regions were declared.
      * The region contents survive a grow via the self-describing region table
-     * (`extend.ts` snapshot/restore), so this is only the layout recipe. */
+     * (`extend.ts` snapshot and restore), so this is only the layout recipe. */
     private readonly _regions;
-    /** Byte size of the opt-in sim-bindings region (#625). 0 ⇒ no region (the
-     * pure-TS default). Captured so the initial `createColumnStore` reserves it;
-     * across a realloc the size is re-derived from the old header by
-     * `optionsFromOld`, so it is not threaded through the grow/extend path. */
+    /** Byte size of the opt-in sim-bindings region. 0 ⇒ no region (the
+     * pure-TS default). Captured so the initial `createColumnStore` reserves it.
+     * Across a realloc the size is re-derived from the old header by
+     * `optionsFromOld`, so it is not threaded through the grow and extend path. */
     private readonly _bindingsRegionBytes;
-    /** Determinism opt-in (#626 / ADR-0020). When `false` (the default), the
-     * canonical-ordering determinism surface (`stateHash` / `snapshotSparse` /
-     * `restoreSparse`) throws `DETERMINISM_DISABLED` rather than running its
-     * sort. Memory-safety invariants (the in-place allocator, ADR-0008) and the
-     * `enabled_count` partition are unaffected — they hold regardless. */
+    /** Determinism opt-in. When `false` (the default), the canonical-ordering
+     * determinism surface throws `DETERMINISM_DISABLED` rather than run its
+     * sort. That surface is `stateHash`, `snapshotSparse` and `restoreSparse`.
+     * The memory-safety invariant of the in-place allocator and the
+     * `enabled_count` partition hold regardless. */
     private readonly _deterministic;
-    /** Whether the determinism surface is enabled (#626). `false` ⇒ `stateHash`
-     * / `snapshotSparse` / `restoreSparse` throw `DETERMINISM_DISABLED`. */
+    /** Whether the determinism surface is enabled. `false` ⇒ `stateHash`,
+     * `snapshotSparse` and `restoreSparse` throw `DETERMINISM_DISABLED`. */
     get deterministic(): boolean;
     /** Guard the canonical-ordering determinism surface. Throws
      * `DETERMINISM_DISABLED` when determinism wasn't opted into, naming the
@@ -276,183 +298,167 @@ export declare class Store implements ObserverHost, QueryHost {
      * (not `DEV`-gated): the surface is cold (never per-tick) so one boolean
      * check is free, and a silent non-canonical digest is the failure mode we're
      * preventing. */
-    private _requireDeterministic;
-    /** Reject `f32`/`f64` fields on a `deterministic: true` world at registration
-     * (#777). IEEE-754 rounds differently across V8 / Bun / Zig at the 1-ULP
-     * level, so a float column in a fixed-update path is a silent per-tick
-     * `stateHash` divergence between client and server — the one thing the
-     * determinism opt-in (ADR-0020) exists to prevent. Non-deterministic worlds
-     * skip this entirely (floats stay allowed), so it costs the default path
-     * nothing. `kind` names the storage class in the error ("component" /
-     * "sparse component"); the array shorthand's `f64` default lands here too, so
-     * a deterministic world must pass an explicit integer type. */
-    private _rejectNonDeterministicFields;
+    private _assertDeterministic;
     /** Rebuild the Int32Array views over the SAB entity-index region
-     * after a host-side SAB realloc (extend / grow). Called from
-     * `_handleBufferResized` BEFORE the user-supplied `onBufferResized`
-     * callback fires so any downstream reader sees coherent views. */
+     * after a host-side SAB realloc (extend and grow). Called from
+     * `_handleBufferResized`, before the user-supplied `onBufferReplaced`
+     * callback fires, so any downstream reader sees coherent views. */
     private _refreshEntityIndexViews;
-    /** Centralised "SAB was just reallocated" handler. Refreshes the
-     * Int32Array views FIRST (so user callbacks observe valid views),
+    /** Centralised "SAB was only reallocated" handler. Refreshes the
+     * Int32Array views first (so user callbacks observe valid views),
      * then mirrors `entityHighWater` into the region's length header,
      * then fires the user-supplied callback. */
     private _handleBufferResized;
-    /** SAB backing every archetype's column views. Read-only handle; the
-     * live mutation happens through `archGetOrCreateFromMask`.
-     * Exposed for tests, snapshot/restore, and the upcoming
-     * `columnStoreStateHash` wire-up. Production reads of column data should
+    /** SAB backing every archetype's column views. Read-only handle. The
+     * live mutation happens through `_archGetOrCreateFromMask`.
+     * Exposed for tests, snapshot and restore, and `columnStoreStateHash`.
+     * Production reads of column data should
      * still go through `Archetype.getColumnRead` (which sources from this
      * SAB under the hood). */
     get columnStore(): ColumnStore;
     /** Resolve a consumer-declared SAB region's byte offset by `region_id`, or
      * 0 when the region is absent (no region was declared with that id). The
-     * generic, de-gamed replacement (#623) for the removed game-named accessors
-     * (`terrain_view` / `spatial_grid_view` / … ); a consumer pairs this with
-     * its own region module (e.g. `@internal/sim`'s region helpers) to
-     * materialise a typed view. TS twin of Zig `abi.find_region`. */
+     * generic replacement for the removed game-named accessors, such as
+     * `terrain_view` and `spatial_grid_view`. A consumer pairs this with its own
+     * region module to materialise a typed view. It is the TS twin of the
+     * `abi.find_region` a WASM backend calls. */
     regionOffset(regionId: number): number;
     /** A handle to a consumer-declared SAB region resolved by `region_id`, or
-     * `null` when absent. Carries the live `buffer`/`view` plus the region's byte
+     * `null` when absent. Carries the live `buffer` and `view` plus the region's byte
      * `offset` and `bytes`, so a consumer's region module can build a TypedArray
      * view over exactly the region's span without re-reading the directory.
-     * Re-fetch after a SAB grow (the offset/view may have moved). (#623) */
+     * Re-fetch after a SAB grow (the offset and view may have moved). */
     regionHandle(regionId: number): ColumnStoreRegionHandle | null;
     /**
      * Stamp every SAB-backed archetype's live `length` into its descriptor's
-     * `row_count` field (#252 / Phase 4 PR 4E). `extendColumnStore` /
+     * `row_count` field. `extendColumnStore` and
      * `growColumnStore` are the only other writers of `row_count`, and they
-     * record the count at the moment of the resize — `Archetype.addEntity`
+     * record the count at the moment of the resize, `Archetype.addEntity`
      * does not update it, so any insertion after the most recent resize
-     * leaves the descriptor stale. Zig systems that drive their per-row loop
-     * off `arch_hdr.row_count` (every `tick_*` export added since PR 3B)
-     * read those stale bytes and silently skip the just-spawned rows.
+     * leaves the descriptor stale. A compute backend that drives its per-row
+     * loop off the descriptor's `row_count` reads those stale bytes and
+     * silently skips the newly spawned rows.
      *
      * Lockstep walk: SAB descriptors are written by `extendColumnStore` in
      * the order non-SAB archetypes are promoted, which is the same id-order
-     * those archetypes occupy in `this.archGraph.archetypes`. Iterating that array
+     * those archetypes occupy in `this._archGraph.archetypes`. Iterating that array
      * once, skipping non-SAB entries, and advancing an `archAddr` cursor
      * by the descriptor's `column_count` lets us write `row_count` without
      * the throwaway `Map<archId, length>` the previous version allocated
-     * on every call (#323). Cheap: descriptor-region seeks only, no column
+     * on every call. Cheap: descriptor-region seeks only, no column
      * I/O.
      *
-     * Gated by `_rowCountsDirty` (#324) — mutation paths
-     * (`flushStructural`, `flushDestroyed`, immediate `destroyEntity`,
-     * `addComponent(s)`, `removeComponent(s)`) set the flag; this method
+     * Gated by `_rowCountsDirty`, mutation paths
+     * (`flushStructural`, `flushDestroys`, immediate `destroyEntity`,
+     * `addComponent(s)`, `removeComponent(s)`) set the flag. This method
      * clears it. Read-only phases that flush only to drain empty buffers
      * pay nothing. */
-    publishRowCountsToDescriptor(): void;
+    publishRowCounts(): void;
     /** FNV-1a-style 32-bit digest over (archetype_id, live_row_count, live
      * column bytes) for each archetype in id order, followed by the sparse
-     * stores (out-of-identity components, ADR-0011) in registration order.
-     * Replaces the per-networked-component fold that compute_state_hash used
-     * pre-#171 §6.1.9 Phase 5 — this is the canonical "live ECS state digest"
-     * for cross-replay determinism.
+     * stores (out-of-identity components) in registration order.
+     * This is the canonical "live ECS state digest" for cross-replay
+     * determinism. It replaces the earlier per-networked-component fold.
      *
-     * **Sparse coverage (#470).** Sparse data lives outside the archetype
-     * graph, so it is folded separately after the archetype loop — per store:
+     * **Sparse coverage.** Sparse data lives outside the archetype
+     * graph, so it is folded separately after the archetype loop, per store:
      * the sparse-component id, the member count, then each member's source
-     * entity index + f64 field words, walked in CANONICAL ascending-index order
+     * entity index + f64 field words, walked in canonical ascending-index order
      * (`SparseComponentStore.canonicalIndices`). Canonical order is what makes
      * the digest insertion-order-independent: two worlds with identical sparse
-     * contents built by different add/remove sequences agree. Keyed by entity
+     * contents built by different add and remove sequences agree. Keyed by entity
      * index, and destruction purges the slot, so a recycled index never carries
      * a stale occupant's data into the hash.
      *
      * It is strictly broader than the prior per-networked-component fold
-     * (covers every column, not just a hand-picked subset of networked
+     * (covers every column, not only a hand-picked subset of networked
      * components), and strictly tighter than `columnStoreStateHash(...)`
      * which scans the full SAB including trailing unused capacity.
      *
-     * **Per-word fold (#326).** The inner column loop folds one 32-bit
-     * word at a time using FNV-1a's `xor + imul(PRIME)` step. This is NOT
-     * byte-for-byte FNV-1a-32 of the column bytes — it's a deterministic
-     * digest with the same equality semantics, ~4× faster than the per-
-     * byte loop it replaces. Trailing 0–3 tail bytes (only possible for
-     * u8/u16 columns at odd row counts) are folded together as a single
+     * **Per-word fold.** The inner column loop folds one 32-bit
+     * word at a time using FNV-1a's `xor + imul(PRIME)` step. This is not
+     * byte-for-byte FNV-1a-32 of the column bytes. It's a deterministic
+     * digest with the same equality semantics, and much quicker than the
+     * per-byte loop it replaces. Trailing 0 to 3 tail bytes (only possible for
+     * u8 or u16 columns at odd row counts) are folded together as a single
      * little-endian word so the algorithm stays branch-free in the inner
      * loop. The 4-byte `id` and `len` headers are folded as words for the
      * same reason. Byte order is little-endian to match the platform's
-     * native TypedArray layout; the digest is opaque (no consumer compares
+     * native TypedArray layout. The digest is opaque (no consumer compares
      * against a literal value), so endianness is an implementation detail
      * rather than wire contract.
      *
      * Determinism: same store ⇒ same digest within a process, and across
-     * processes on the same architecture (which is all `replay_match`
-     * needs — both replays run the same algorithm on the same words).
+     * processes on the same architecture, which is all a lockstep replay
+     * needs, because both replays run the same algorithm on the same words.
      *
-     * **Opt-in (#626 / ADR-0020).** Throws `DETERMINISM_DISABLED` unless the
+     * **Opt-in.** Throws `DETERMINISM_DISABLED` unless the
      * Store was constructed with `{ deterministic: true }`. The canonical
      * ordering this fold relies on (sparse `canonicalIndices`, sorted relation
      * target sets) is the determinism tax the flag gates. */
     stateHash(): number;
-    private archGet;
-    /** Look up the `EntityID` at `row` in archetype `archetype_id`. Used
-     * by a WASM system to resolve an
-     * `EntityID` from an event-ring payload — Zig writes
-     * `(archId, row, …)` to the event ring,
-     * and TS bridges it back through `ctx.emit(...)` via this method. (#250 /
-     * Phase 4 PR 4D)
+    private _archGet;
+    /** Look up the `EntityID` at `row` in archetype `archetype_id`. A compute
+     * backend resolves an `EntityID` from an event-ring payload through it. The
+     * backend writes `(archId, row, …)` to the event ring, and TS bridges it
+     * back through `ctx.emit(...)` via this method.
      *
      * Throws `ECSError` if `archetype_id` is out of range or `row` is
-     * past the archetype's live row count — these would indicate a
-     * ring-payload corruption or a stale row index (extend / grow
-     * happened mid-tick), both of which are bugs the parity test would
-     * surface. */
+     * past the archetype's live row count. Either one means a corrupt
+     * ring payload or a stale row index (an extend or a grow happened
+     * mid-tick), and both are defects. */
     entityIdAtRow(archetypeId: number, row: number): EntityID;
-    /** Find or create an archetype for the given component mask — see
+    /** Find or create an archetype for the given component mask, see
      * `ArchetypeGraph.getOrCreateFromMask`. */
-    private archGetOrCreateFromMask;
-    /** Bulk variant of `archGetOrCreateFromMask` — one `extendColumnStore`
-     * call for the whole batch (Phase C prewarm, #213). See
-     * `ArchetypeGraph.createManyFromMasks`. */
+    private _archGetOrCreateFromMask;
+    /** Bulk variant of `_archGetOrCreateFromMask`, one `extendColumnStore`
+     * call for the whole batch (the prewarm pass). See
+     * `ArchetypeGraph.getOrCreateFromMasks`. */
     archCreateManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
-    /** Snapshot every existing archetype's SAB rows, call `extendColumnStore`
-     * once with `newSpecs`, then refresh every pre-existing SAB-backed
-     * Archetype's TypedArray views. The single `existing` snapshot is the
-     * key win in the bulk variant — single-mask creation rebuilds it per
-     * call (i.e. N times for N new archetypes). */
-    private _archExtendStoreWithNewSpecs;
-    /** Materialise the `Archetype` object for a freshly-minted graph node —
-     * binds the graph's topology to THIS store's column backing and grow
+    /** Call `extendColumnStore` once with `newSpecs`, then refresh every
+     * pre-existing SAB-backed Archetype's TypedArray views when the extend had
+     * to realloc. The `existing` row counts are built only when that realloc
+     * path runs: the in-place path moves no rows and reads no list, and to walk
+     * every archetype on every extend made the cost of the N-th archetype grow
+     * with N. The bulk variant makes one extend for many archetypes, so the
+     * list is built at most one time for them all. */
+    private _extendStore;
+    /** Materialise the `Archetype` object for a freshly-minted graph node,
+     * binds the graph's topology to this store's column backing and grow
      * handler (`ArchetypeGraphHost.materialize`). Store-owned so the graph
      * never touches `_columnStore`. */
     private _materializeArchetype;
-    /** Push a newly-installed archetype into every registered query whose masks
-     * it satisfies (`ArchetypeGraphHost.fanIntoQueries`; the query registry
-     * stays on Store). No epoch bump — see the note in `ArchetypeGraph.install`. */
-    private _fanIntoQueries;
     /** Resolve "add component_id to archetype_id" → target ArchetypeID (edge-cached). */
-    private archResolveAdd;
+    private _archResolveAdd;
     /** Resolve "remove component_id from archetype_id" → target ArchetypeID (edge-cached). */
-    private archResolveRemove;
+    private _archResolveRemove;
     createEntity(): EntityID;
-    /** Allocate an entity slot WITHOUT placing it in the empty archetype, for
-     * the template spawn paths. Returns the packed `EntityID`; the slot index
-     * is left in `entityAllocator.lastIndex`. Skips the empty-archetype
+    /** Allocate an entity slot without placing it in the empty archetype, for
+     * the template spawn paths. Returns the packed `EntityID`. The slot index
+     * is left in `_entityAllocator.lastIndex`. Skips the empty-archetype
      * membership write `createEntity` performs (the caller installs the real
      * archetype + row). This *commits* the slot (bumps counts, stamps the
-     * generation so `isAlive` is already true), so the caller MUST have
+     * generation so `isAlive` is already true), so the caller must have
      * reserved the column capacity for the row first
-     * (`Archetype.ensureRowCapacity`) — otherwise a cap throw from the
-     * subsequent append leaves the slot phantom-alive (#775). */
+     * (`Archetype.reserveRows`), otherwise a cap throw from the
+     * subsequent append leaves the slot phantom-alive. */
     private _allocEntity;
     /** Pre-check that `count` fresh entity slots can be allocated without
-     * exhausting the entity-index space, so `spawnMany` commits all-or-nothing
-     * (#775). `_allocEntity`'s own per-call high-water guard would otherwise
+     * exhausting the entity-index space, so `spawnMany` commits all-or-nothing.
+     * `_allocEntity`'s own per-call high-water guard would otherwise
      * throw `EID_MAX_INDEX_OVERFLOW` partway through the alloc loop, leaving the
      * slots it already committed phantom-alive. Free-list reuse covers the first
-     * `entityFreeIndices.length` slots; only the remainder draws down the
+     * `entityFreeIndices.length` slots. Only the remainder draws down the
      * high-water headroom. */
-    private _ensureEntityIndexCapacity;
-    /** Resolve a template: compute the target archetype (creating it if absent —
+    private _assertEntityIndexCapacity;
+    /** Build a template: compute the target archetype (creating it if absent,
      * fits the prewarm model), pre-flatten default field values into
      * `_flatColumns` order, and build the override index (field name → flat
-     * column index; `TEMPLATE_OVERRIDE_AMBIGUOUS` for a name shared by more than
+     * column index. `TEMPLATE_OVERRIDE_AMBIGUOUS` for a name shared by more than
      * one component, which a flat override cannot target). */
-    resolveTemplate(entries: readonly TemplateEntryData[]): Template;
+    createTemplate(entries: readonly TemplateEntryData[]): Template;
     /** Resolve an override key to its flat column index, with the DEV guards
-     * for unknown and ambiguous field names; `-1` means skip (the production
+     * for unknown and ambiguous field names. `-1` means skip (the production
      * fallback where DEV would have thrown). */
     private _resolveOverrideColumn;
     /** Apply per-instance overrides to the freshly-spawned row. Each key is a
@@ -466,20 +472,20 @@ export declare class Store implements ObserverHost, QueryHost {
      * applies any per-instance overrides. */
     spawn(p: Template, overrides?: Record<string, number | undefined>): EntityID;
     /** Bulk-spawn `count` identical entities into the template's archetype. The
-     * field writes are O(columns) — one `TypedArray.fill` per column via
-     * `addEntitiesWithValues` — not O(count×columns). Returns the new ids in
+     * field writes are O(columns), one `TypedArray.fill` per column via
+     * `addEntitiesWithValues`, not O(count×columns). Returns the new ids in
      * spawn order. */
     spawnMany(p: Template, count: number, overrides?: Record<string, number | undefined>): EntityID[];
     /** Immediately destroy an entity, removing it from its archetype.
      *
-     * With no `delete`/`clear` target-cleanup policy registered (the common
-     * case) this tears the one entity down and returns — no allocation. When a
+     * With no `delete` or `clear` target-cleanup policy registered (the common
+     * case) this tears the one entity down and returns, no allocation. When a
      * policy is in play, a `delete`-target's sources are appended to a local
-     * work-list this method then drains in the same iterative pass (#473, #492):
+     * work-list this method then drains in the same iterative pass:
      * the `work.length` re-read drives chains and trees out without recursion, so
      * depth is bounded by entity count, not tree depth. This mirrors the deferred
-     * `flushDestroyed` buffer mechanism — both paths are iterative and reach the
-     * identical end state; the only difference is the shared `pendingDestroy`
+     * `flushDestroys` buffer mechanism, both paths are iterative and reach the
+     * identical end state. The only difference is the shared `pendingDestroy`
      * buffer there vs. a local work-list here. `isAlive` dedups a source reached
      * twice (diamonds) and terminates cycles, exactly as the generation guard does
      * in the deferred loop. */
@@ -488,71 +494,99 @@ export declare class Store implements ObserverHost, QueryHost {
      * then recycle (or retire) its slot. Shared by both immediate-destroy entry
      * points (the fast no-cascade path and the work-list driver in
      * `destroyEntity`). When `cascade` is non-null, a `delete`-policy target's
-     * surviving sources are appended to it for the driver to drain (#473, #492);
+     * surviving sources are appended to it for the driver to drain.
      * `null` skips that collection for callers that cannot cascade. The caller
      * must have already confirmed `id` is alive. */
     private _destroyOne;
     /**
-     * Liveness check, **fail-closed** against forged / retired / out-of-bounds
-     * handles (#778). For a general-purpose engine that may receive a handle from
-     * serialization, IPC, or any untrusted caller, three malformed inputs must read
+     * Liveness check, **fail-closed** against a forged, retired or out-of-bounds
+     * handles. For a general-purpose engine that may receive a handle from
+     * serialization, ipc, or any untrusted caller, three malformed inputs must read
      * dead rather than alias a slot:
-     *   - **Out of range** — an `id` outside the 31-bit packed space (`< 0` or
+     *   - **Out of range**, an `id` outside the 31-bit packed space (`< 0` or
      *     `> MAX_ENTITY_ID`). Without this, the 20-bit index mask below silently
-     *     folds garbage high bits onto a valid slot. (Same bound the snapshot /
-     *     postMessage decode applies, #723.)
-     *   - **Tombstone generation** — a handle carrying `RETIRED_GENERATION`, which
+     *     folds garbage high bits onto a valid slot. (The snapshot decode and the
+     *     `postMessage` decode apply the same bound.)
+     *   - **Tombstone generation**, a handle carrying `RETIRED_GENERATION`, which
      *     the allocator stamps into a retired slot and never issues to a live
      *     entity, would otherwise match a retired slot's parked generation and read
      *     alive (the ABA tombstone, previously documented as a known gap).
      * Both guards are comparisons predicted not-taken on the live path, so a
-     * well-formed handle pays two branches and nothing else (#778 measured).
+     * well-formed handle pays two branches and nothing else.
      */
     isAlive(id: EntityID): boolean;
+    /**
+     * Liveness and the packed index in one result: the entity index if `id` is
+     * live, else `-1`. Same three fail-closed guards as `isAlive` (documented
+     * above), and the sole implementation of them, `isAlive` is a comparison on
+     * top of this.
+     *
+     * Why it returns the index instead of a boolean: every by-id caller needs
+     * both answers, and the pair used to cost two derivations of the same index.
+     * `hasComponent` called `isAlive(id)`, which computed `getEntityIndex(id)`
+     * internally, and then computed `getEntityIndex(id)` again to reach
+     * `_entityArchetypes`. The generational check has already touched the index. A
+     * caller that is about to index a parallel array with it should be handed the
+     * one that was computed, not re-derive it. The generations read is inlined
+     * here for the same reason, rather than delegated to
+     * `_entityAllocator.isAliveIndex`, which stays as the index-domain entry point
+     * for callers that already hold an index.
+     *
+     * **This gives much less than it appears to give.** The estimate for this
+     * change was a large decrease. The measurement shows that `has` and `isAlive`
+     * are only a little faster. The decrease is real, but it is much smaller than
+     * the estimate. The work that we removed was truly not necessary. But V8
+     * already made both one-line functions inline, and it already removed most of
+     * the duplicated calculation. Therefore "the work is plainly not necessary" is
+     * not an argument about performance for a jit compiler. This note stops the
+     * next reader from making the same estimate again.
+     */
+    private _liveIndex;
     get entityCount(): number;
     /** An archetype's row count moved from `preLen` to its current
      * `arch.length` on a **shrink** (rows removed: the source of a transition, a
-     * destroy, a batch-source drain). Always marks SAB row counts dirty (#324 —
-     * the descriptor walk just needs "something moved"); bumps the query-dirty
-     * epoch (#327) only on a `length` 0/non-zero crossing, the only case where
-     * `Query._nonEmptyArchetypes` can change on a shrink (#328). Mutations that
+     * destroy, a batch-source drain). Always marks SAB row counts dirty
+     * (the descriptor walk only needs "something moved"). It bumps the
+     * query-dirty epoch only when `length` crosses zero, the only case where
+     * `Query._nonEmptyArchetypes` can change on a shrink. Mutations that
      * move row counts within the same side (6→5) leave the non-empty set unchanged
      * and skip the bump.
      *
-     * A shrink does **not** need the `enabledCount` crossing test (#812): the
-     * only enabled-count move it can make is 1→0 (the last enabled row leaves an
-     * archetype that keeps disabled rows), which leaves the archetype in a default
-     * query's non-empty list as a harmless stale *inclusion* — `count`/`forEach`
-     * bound on `enabledCount` (now 0) iterate it zero times. Only a **grow** into
+     * A shrink does **not** need the `enabledCount` crossing test. The only
+     * enabled-count move it can make is 1→0, when the last enabled row leaves an
+     * archetype that keeps disabled rows. That leaves the archetype in a default
+     * query's non-empty list as a harmless stale *inclusion*. `count` and
+     * `forEach` bound on `enabledCount` (now 0), so they iterate it zero times.
+     * Only a **grow** into
      * an all-disabled archetype can stale-*exclude* a live row, so the enabled
      * crossing lives in `_onArchGrow`, off this path.
      *
-     * **Inlining-sensitive — keep the body tiny.** This function is called
-     * once or twice per immediate-mode `addComponent` / `removeComponent` and the
-     * mutation hot path depends on it being inlined at every call site.
-     * #351 / PR #353 added an `if (registeredQueries.length === 0) return;`
-     * gate to skip the bump for no-query workloads — bench showed it
-     * regressed `mutation: churn_loop` 16-18% because the extra statement
-     * pushed the function past V8's per-call inlining budget. Reverted in
-     * PR #355. Any future change here needs a `bench-vs-commit` run before
-     * merging, not just code review. */
-    private _onArchLenChange;
-    /** An archetype **grew** — rows were appended (the target of a transition, a
-     * spawn, a batch-target fill). Like `_onArchLenChange` it marks row counts
+     * Inlining-sensitive, keep the body tiny. Each immediate-mode `addComponent`
+     * or `removeComponent` calls it once or twice. The mutation hot path depends
+     * on the inline at every call site.
+     * An earlier change added an `if (_registeredQueries.length === 0) return;`
+     * gate to skip the bump for no-query workloads. The mutation churn loop got
+     * far slower, because the extra statement pushed the function past V8's
+     * per-call inlining budget. The gate is no longer in the code. Measure the
+     * mutation hot path before you merge a change here. Code review alone is
+     * not sufficient. */
+    private _onArchShrink;
+    /** An archetype **grew**, rows were appended (the target of a transition, a
+     * spawn, a batch-target fill). Like `_onArchShrink` it marks row counts
      * dirty and bumps the query-dirty epoch on a `length` 0/non-zero crossing
      * (`includeDisabled` membership), but it *also* bumps on an `enabledCount`
-     * 0→1 crossing (#812). The non-empty filter is field-split (#577): a default
+     * 0→1 crossing. The non-empty filter is field-split: a default
      * query keeps archetypes with `enabledCount > 0`. An enabled row appended to
      * an archetype that is non-empty but all-disabled (`length > 0,
      * enabledCount == 0`) crosses `enabledCount` 0→1 without touching `length`,
-     * so the `preLen` test alone (the valid-while-`enabledCount === length`
-     * pre-#577 proxy) misses it and a cached default query keeps a stale
-     * `_nonEmpty` list. Only grows can do this, so only grow sites carry the test.
+     * so the `preLen` test alone (the earlier proxy, valid only while
+     * `enabledCount === length`) misses it and a cached default query keeps a stale
+     * `nonEmptyArchs` list. Only grows can do this, so only grow sites carry the test.
      *
      * **Precondition: ≥1 row was appended** (every caller adds at least one row),
-     * so `arch.length > 0` afterward — which is why the crossings simplify and the
-     * body stays inlinable (the inlining caveat on `_onArchLenChange` applies
-     * here too; verified with `bench-vs-commit mutation`). The general
+     * so `arch.length > 0` afterward, which is why the crossings simplify and the
+     * body stays inlinable (the inlining caveat on `_onArchShrink` applies
+     * here too). The general
      * `(pre === 0) !== (post === 0)` boundary test collapses given the post side:
      *   - `length`: post > 0 always ⇒ a crossing iff `preLen === 0`.
      *   - `enabledCount`: non-decreasing on a grow ⇒ a 0-crossing iff it was 0
@@ -561,17 +595,17 @@ export declare class Store implements ObserverHost, QueryHost {
      *     read is short-circuited away on the hot path (`preLen` or `preEnabled`
      *     non-zero), so a no-disabled workload pays only two scalar compares. */
     private _onArchGrow;
-    /** Dirty bookkeeping for an enable/disable toggle (#577). `length` is
-     * unchanged (no row added/removed) but `enabled_count` moved, so: republish
-     * row counts (the descriptor's `enabled_count` changed, so the WASM sim and
-     * snapshot see the new partition), and bump the query epoch only when the
-     * *enabled* count crossed 0 — the boundary at which an archetype enters/leaves
-     * a query's non-empty set (`Query._nonEmpty` filters on `entityCount`, which
-     * is now `enabled_count`). */
+    /** Dirty bookkeeping for an enable and disable toggle. `length` is
+     * unchanged (no row added or removed) but `enabled_count` moved, so: republish
+     * row counts, because the descriptor's `enabled_count` changed and a compute
+     * backend and the snapshot must see the new partition. Bump the query epoch only when
+     * the *enabled* count crossed 0. That is the boundary at which an archetype
+     * enters and leaves a query's non-empty set, because `Query.nonEmptyArchs`
+     * filters on `entityCount`, which is now `enabled_count`. */
     private _onArchEnabledChange;
     /** Immediately disable an entity (idempotent). The entity must hold at least
-     * one component — a component-less entity occupies no archetype row, so it
-     * cannot be partitioned (a `DEV` error; prod no-op). */
+     * one component, a component-less entity occupies no archetype row, so it
+     * cannot be partitioned (a `DEV` error, prod no-op). */
     disableEntity(id: EntityID): void;
     /** Immediately enable an entity (idempotent). */
     enableEntity(id: EntityID): void;
@@ -579,250 +613,306 @@ export declare class Store implements ObserverHost, QueryHost {
      * disabled (it has no row to partition). */
     isDisabled(id: EntityID): boolean;
     /** 0-crossing detection for the per-entity flush paths (`_flushAdds`,
-     * `_flushRemoves`) without per-entity Map traffic — the same cost the
-     * destroy drain shed in #457. Each touched archetype is stamped with the
+     * `_flushRemoves`) without per-entity Map traffic, the same cost the
+     * destroy drain also avoids. Each touched archetype is stamped with the
      * current flush epoch (`Archetype._flushSeenEpoch`), its pre-length and
-     * pre-enabled-count recorded on first sight (`_flushPreLen` /
-     * `_flushPreEnabled`), and pushed onto this scratch list;
+     * pre-enabled-count recorded on first sight (`_flushPreLen` and
+     * `_flushPreEnabled`), and pushed onto this scratch list
      * `_settleFlushDirty` walks the list once after the loop. The field
      * accesses per entity replace a `Map.has` + `Map.set` hash probe pair. The
      * epoch is bumped at settle so the next flush re-records. */
     private _flushEpoch;
     private readonly _flushTouched;
     /** Resolve dirty flags for a per-entity batch flush from the captured
-     * pre-counts. Marks row counts dirty if any archetype was touched; bumps
+     * pre-counts. Marks row counts dirty if any archetype was touched. Bumps
      * the query epoch once if any touched archetype crossed the 0 boundary on
      * *either* `length` (includeDisabled membership) or `enabledCount`
-     * (default-query membership) — the deferred analog of the immediate
-     * `_onArchLenChange` two-field check (#812). A single bump is sufficient
+     * (default-query membership), the deferred analog of the immediate
+     * `_onArchShrink` two-field check. A single bump is sufficient
      * (queries only need to know "something changed"). Clears the touched list
      * and advances the flush epoch on exit. */
     private _settleFlushDirty;
     destroyEntityDeferred(id: EntityID): void;
-    /** Buffer an enable/disable toggle for the phase flush (#577). The row swap a
+    /** Buffer an enable and disable toggle for the phase flush. The row swap a
      * toggle performs would corrupt a `forEach` over that archetype if applied
-     * mid-system, so it is deferred like add/remove. */
+     * mid-system, so it is deferred like an add and a remove. */
     disableEntityDeferred(id: EntityID): void;
     enableEntityDeferred(id: EntityID): void;
-    /** Drain buffered enable/disable toggles, applying each in operation order via
+    /** Drain buffered enable and disable toggles, applying each in operation order via
      * the immediate path (which is idempotent and updates dirty flags). Called at
-     * the flush boundary after structural adds/removes settle, so a toggle sees the
+     * the flush boundary after structural adds and removes settle, so a toggle sees the
      * entity's final archetype placement for the tick.
      *
-     * When an onDisable/onEnable observer is registered (`_toggleObserverCount >
-     * 0`, #677) this also collects effective toggle events into `_obsEvents` for
+     * When an onDisable and onEnable observer is registered (`_toggleObserverCount >
+     * 0`) this also collects effective toggle events into `_obsEvents` for
      * the dispatch hook, collapsed to one event per *net* transition across the
      * drain (see `_toggleInitial`). The no-observer path is byte-for-byte the
-     * pre-#677 drain. */
+     * earlier drain. */
     private _flushToggles;
-    /** Fan one entity's net toggle transition out to an onDisable / onEnable event
-     * per carried component (#677). Walks the entity's archetype mask through the
-     * matching pre-bound bit visitor; a component-less entity (no row) carries
+    /** Fan one entity's net toggle transition out to an onDisable and onEnable event
+     * per carried component. Walks the entity's archetype mask through the
+     * matching pre-bound bit visitor. A component-less entity (no row) carries
      * nothing and is skipped. */
     private _collectToggle;
     get pendingToggleCount(): number;
     /** Flush all buffered entity destructions in batch.
      *
      * When onRemove observers are registered (`_structuralObserverCount > 0`),
-     * a destroy fires onRemove for every component the entity carried — a destroy
-     * *is* a remove of the whole mask — collected here and dispatched by the
+     * a destroy fires onRemove for every component the entity carried, a destroy
+     * *is* a remove of the whole mask, collected here and dispatched by the
      * `flushStructural` fixed-point loop, the only caller in that mode (it drains
      * `pendingDestroy` each round so the trailing `ctx.flush()` call is a no-op).
      * Same commit-then-observe discipline as `_flushRemoves`: the entity is fully
      * freed before the callback runs, so onRemove receives the (now dead) eid as
      * the identity of what was destroyed, not a live handle to read. The
-     * no-observer path is byte-for-byte unchanged (`collecting` gate). #531.
+     * no-observer path is byte-for-byte unchanged (`collecting` gate).
      *
      * Re-entrancy: while the observed fixed point owns the flush, the loop
-     * drains destroys itself via `_drainDestroyed`, so a re-entrant
+     * drains destroys itself via `_flushDestroys`, so a re-entrant
      * `ctx.flush()` from a callback no-ops (the guard lives in
-     * `DeferredCommandBuffer.flushDestroyed`) — otherwise it would collect
+     * `DeferredCommandBuffer.flushDestroys`), otherwise it would collect
      * into the shared `_obsEvents` scratch mid-dispatch and corrupt it. */
-    flushDestroyed(): void;
-    private _drainDestroyed;
+    flushDestroys(): void;
+    private _flushDestroys;
     get pendingDestroyCount(): number;
     addComponentDeferred(entityId: EntityID, def: ComponentDef<Record<string, never>>): void;
     addComponentDeferred<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): void;
     removeComponentDeferred(entityId: EntityID, def: ComponentDef): void;
-    /** Phase-boundary structural flush. The drain policy — no-observer fast
-     * path, observed fixed point (adds/removes → destroys → toggles),
-     * convergence guard, re-entrancy — lives in `DeferredCommandBuffer`
-     * (H1 step 4); the batch appliers it drives are the `_flush*` /
-     * `_drainDestroyed` methods below. */
+    /** Phase-boundary structural flush. The drain policy, no-observer fast
+     * path, observed fixed point (adds and removes → destroys → toggles),
+     * convergence guard, re-entrancy, lives in `DeferredCommandBuffer`.
+     * The batch appliers it drives are the `_flush*` and
+     * `_flushDestroys` methods below. */
     flushStructural(): void;
     /** Batch-apply all deferred component additions. */
     private _flushAdds;
     /** Batch-apply all deferred component removals. */
     private _flushRemoves;
     get pendingStructuralCount(): number;
-    /** Set the per-component observation flags from the registry's aggregate of
-     * live observers for `cid`. Maintains `_structuralObserverCount` and
-     * `_toggleObserverCount` (#677) (the fast-path gates) and lazily allocates the
+    /** Record what one consumer of the change feed asks the store to collect
+     * for `cid`, then apply the OR of every consumer's ask.
+     *
+     * `consumer` is the plugin name. The observer registry passes
+     * `"observers"`. One consumer dropping a flag never takes that flag away
+     * from another, which is why the merge sits in front of the transition
+     * logic. All-false is the same as absent. Cold path: a consumer calls this
+     * when it gains or loses an observer. */
+    configureObservation(consumer: string, cid: number, flags: ObservationFlags): void;
+    /** Set the per-component observation flags from the merged ask of every
+     * consumer for `cid`. Maintains `_structuralObserverCount` and
+     * `_toggleObserverCount` (the fast-path gates) and lazily allocates the
      * dirty list when per-entity onSet tracking turns on. */
-    _configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
-    /** Record a per-entity onSet "changed" event for the entity. Called from the
-     * field-write path (`SystemContext.setField` / `markChanged`) and gated by
-     * the caller on `_anyDirtyTracked`. Appends to the dirty list only if the
-     * dedup bit was clear (the ADR-0012 list + dedup-bit mechanism). */
-    _noteSet(def: ComponentHandle, eid: EntityID): void;
-    private _growDirtyMarks;
-    /** Detach and return the dirty-row list for `cid`, clearing its dedup bits and
-     * leaving the store with a fresh empty list (so re-dirties during the drain
-     * accumulate for the NEXT tick, not this one). Returns a shared empty array
-     * when nothing is dirty. Caller owns the returned array. */
-    _takeDirty(cid: number): EntityID[];
-    /** Clear any dirty dedup bits for a freed entity index across every tracked
-     * component, so a recycled slot at the same index can be marked afresh. Gated
-     * by `_anyDirtyTracked` at the destroy call sites. */
-    private _clearDirtyForIndex;
+    private _applyObservation;
+    /** Give `cid` a row tick plane: one change tick for each row of every
+     * archetype that holds it, stamped by every write path. The row grain of
+     * change detection. An entity-level onSet observer calls this. Idempotent,
+     * and never undone. Cold. */
+    trackRows(def: ComponentHandle | SparseComponentDef): void;
+    /** Record what one consumer of the change feed asks the store to collect
+     * for sparse component `sid`, then apply the OR of every consumer's ask.
+     * Same merge rule as the dense form. Cold path. */
+    configureSparseObservation(consumer: string, sid: number, hasSet: boolean): void;
+    /** Row ticks on for sparse component `sid`, or the pending records dropped
+     * when the last consumer of its change feed leaves. */
+    private _applySparseObservation;
+    /** Collect the members of sparse component `sid` recorded since the last
+     * drain, for the entity-level onSet dispatch. `run` is the change tick of
+     * the dispatch. A member is alive by construction, because a destroy purges
+     * it, and the walk skips a disabled one, which default queries hide. The
+     * component-level change tick gates the walk, so an idle component costs
+     * one compare. Member order. The result array is reused. */
+    drainSparseSet(sid: number, run: number): EntityID[];
+    /** The row tick of `entityId`'s sparse component, 0 for a non-member, for
+     * `ctx.sparseChanged`. Throws when the component keeps no row ticks. */
+    sparseTickOf(def: SparseComponentDef, entityId: EntityID): number;
+    /** The store a mutable sparse cursor stamps through on each `at()`
+     * (ref.ts `createSparseCursor`). */
+    sparseTickPlane(def: SparseComponentDef): SparseComponentStore;
+    /** `trackRows` by component id, for the observer registry, which holds
+     * the id alone. */
+    private _trackRowsById;
+    /** The list length past which a frame switches to the scan. A list entry
+     * costs a push, three checks and a sort slot. A scan costs one compare per
+     * row of each stamped archetype, and those rows are at most the live
+     * entities, so a cap of a fraction of the live count keeps the list cost
+     * paid below the scan cost that replaces it, whatever the world's size. */
+    private _listCap;
+    /** Record a row for the entity-level onSet of `cid`, from a path that has
+     * resolved the archetype and the row (`setField`, `ref`, a cursor). Gated
+     * by the caller on `anyDirtyTracked`. Stamps the row tick, and pushes the
+     * entity onto the dirty list when the row's previous stamp lay at or below
+     * the last drain: the row is then new to the list. Hot path on the by-id
+     * writes of a tracked component: two loads, one compare, one store. */
+    noteSet(cid: number, arch: Archetype, row: number, eid: EntityID): void;
+    /** `noteSet` for a caller that holds the entity alone (`ctx.markChanged`).
+     * A dead entity, and one that does not hold the component, record nothing. */
+    noteSetEntity(def: ComponentHandle, eid: EntityID): void;
+    /** A chunk loop took the row tick column of `cid` (`cols.ticks`). Its
+     * stores make no list entry, so the next drain scans the plane. */
+    noteScan(cid: number): void;
+    /** Collect the rows recorded for `cid` since the last drain, for the
+     * entity-level onSet dispatch. `run` is the change tick of the dispatch.
+     *
+     * Two sources. `scanned` comes from a walk of the tick plane of every
+     * archetype stamped since the last drain, taken only in a frame where a
+     * chunk loop took `cols.ticks(def)`. A row inside the enabled partition is
+     * alive, a member and enabled by construction, so the dispatch fires these
+     * with no check, and the walk costs one compare per row of each stamped
+     * archetype. `listed` comes from the dirty list the by-id paths keep, minus
+     * the entries a scan covers. A listed entity may have died, lost the
+     * component or been disabled since its record, so the dispatch checks
+     * each. Both come back in row order, and the result object is reused. */
+    drainSet(cid: number, run: number): DrainResult;
     /** Visit every non-empty archetype containing `cid` whose component-column
-     * changed at or after `baseline`, in canonical (ascending archetype-id) order
-     * — the archetype-granular onSet detection point. Reuses the existing
-     * per-archetype change tick (free; no write-path cost). */
-    _forEachChangedArchetype(cid: number, baseline: number, cb: (arch: Archetype) => void): void;
+     * changed after `baseline`, in canonical (ascending archetype-id) order,
+     * the archetype-granular onSet detection point. Reuses the existing
+     * per-archetype change tick (free, no write-path cost). `baseline` is the
+     * change tick of the consumer's previous visit, so a stamp equal to it was
+     * made by that visit and is not reported again. */
+    forEachChangedArchetype(cid: number, baseline: number, cb: (arch: Archetype) => void): void;
     /** Enabled live entities currently carrying `cid`, used by `yieldExisting` to
-     * replay onAdd on registration. Bounded by `enabled_count` (#677): a disabled
+     * replay onAdd on registration. Bounded by `enabled_count`: a disabled
      * entity is excluded from default queries, so seeding it via onAdd would
-     * publish a row that an immediate onDisable should have removed — it is simply
-     * absent at seed (the "delete on disable" semantics). Unordered here — the
+     * publish a row that an immediate onDisable should have removed. It is
+     * absent at seed (the "delete on disable" semantics). Unordered here, the
      * registry radix-sorts. */
-    _collectEntitiesWithComponent(cid: number): EntityID[];
+    collectEnabledWith(cid: number): EntityID[];
     registerComponent<S extends Record<string, TypedArrayTag>>(schema: S, name?: string): ComponentDef<S>;
     /** `'Pos' (component 5)` when the component was registered with a debug
-     * name, else `component 5` — the label diagnostics interpolate. */
+     * name, else `component 5`, the label diagnostics interpolate. */
     componentLabel(cid: number): string;
-    /** Return the field index assigned to `(def, fieldName)` at component
-     * registration. Indexes are insertion-order, zero-based, and stable for
-     * the lifetime of the ECS. Used by systems that pass `(component_id,
-     * field_id)` pairs across the WASM FFI (PR 3C / #231). */
+    /** The field index assigned to `(def, fieldName)` at registration. A system
+     * that passes `(component_id, field_id)` pairs across the WASM FFI resolves
+     * them once, at setup. */
     fieldIdOf(def: ComponentHandle, fieldName: string): number;
     /** Register a sparse component or tag. Unlike `registerComponent`, this
      * allocates from a separate id space and never touches the archetype mask,
      * so it does **not** count against `STORE_DESCRIPTOR_COMPONENT_LIMIT`. See
-     * ADR-0011 and `sparse_store.ts`. */
+     * `sparse_store.ts`. */
     registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S, name?: string): SparseComponentDef<S>;
-    /** Sparse sibling of `componentLabel` — sparse ids are a separate id space. */
+    /** Sparse sibling of `componentLabel`, sparse ids are a separate id space. */
     sparseLabel(sid: number): string;
-    /** Allocate the backing sparse store WITHOUT the #777 float guard, for
-     * engine-internal backings whose `f64` holds an EXACT integer rather than a
+    /** Allocate the backing sparse store without the float guard, for
+     * engine-internal backings whose `f64` holds an exact integer rather than a
      * user quantity: the exclusive-relation `{ target }` slot stores an `EntityID`
-     * (≤ 2^53, so f64 is bit-exact and cross-host identical — the ban targets float
+     * (≤ 2^53, so f64 is bit-exact and cross-host identical, the ban targets float
      * *arithmetic* rounding, which a target slot never undergoes). User schemas go
      * through `registerSparseComponent`, which guards first. */
     private _pushSparseStore;
-    private sparseStoreOf;
+    private _sparseStoreOf;
     /** Add (or overwrite) a sparse component on an entity. No archetype
-     * transition, no row copy — the entity's `archetype_id` is unchanged. */
+     * transition, no row copy, the entity's `archetype_id` is unchanged. */
     addSparse(entityId: EntityID, def: SparseComponentDef, values?: Record<string, number>): void;
     /** Remove a sparse component from an entity. No-op if absent. */
     removeSparse(entityId: EntityID, def: SparseComponentDef): void;
-    /** Total, like `hasComponent` — `false` for a dead entity, never a throw. */
+    /** Total, like `hasComponent`, `false` for a dead entity, never a throw. */
     hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
     getSparseField(entityId: EntityID, def: SparseComponentDef, field: string): number;
     setSparseField(entityId: EntityID, def: SparseComponentDef, field: string, value: number): void;
     /** Drop all sparse data for a destroyed entity index so a recycled slot
-     * can't inherit it. Gated by the caller on `sparseStores.length > 0` to
+     * can't inherit it. Gated by the caller on `_sparseStores.length > 0` to
      * keep the destroy hot path free when sparse storage is unused. */
     private _purgeSparse;
+    /** A sparse component's field names in schema order, the cursor's reserved
+     * name check (ref.ts). */
+    sparseFieldNames(def: SparseComponentDef): readonly string[];
+    /** A sparse component's accessor column array (ref.ts). Its identity is
+     * stable for the life of the store, so a cursor holds it from creation. */
+    sparseAccessorColumns(def: SparseComponentDef): AccessorColumns;
+    /**
+     * The DEV-only check a sparse cursor runs on every `at()` (ref.ts
+     * `createSparseCursor`): the access declaration (the same reason
+     * `cursorBinder` checks on `at()`), the liveness of the entity, and its
+     * membership. Production code never calls it, so a read of a non-member
+     * there gives whatever the column holds at that index, test with
+     * `hasSparse` first when the component can be absent, as `getSparseField`
+     * asks too.
+     */
+    sparseCursorCheck(def: SparseComponentDef, write: boolean): SparseCursorCheck;
     /** Serialize the sparse stores **and** relation side data to a self-contained
-     * byte buffer — the sparse half of a world snapshot (the dense half is the
-     * SAB snapshot). Two framed sections: the sparse stores (`snapshot_sparse_-
-     * stores` — exclusive relation targets + multi membership ride here) followed
-     * by the relation side data (`snapshotRelations` — multi forward target
+     * byte buffer, the sparse half of a world snapshot (the dense half is the
+     * SAB snapshot). Two framed sections: the sparse stores
+     * (`snapshotSparseStores`, exclusive relation targets and multi membership
+     * ride here) followed
+     * by the relation side data (`snapshotRelations`, multi forward target
      * sets, which live outside the sparse store). Both are written in canonical
      * entity-index order, so two worlds with identical contents inserted in
-     * different orders snapshot byte-for-byte the same (#470). The reverse index
-     * is derived and never serialized — `restoreSparse` rebuilds it. Pairs with
+     * different orders snapshot byte-for-byte the same. The reverse index
+     * is derived and never serialized, `restoreSparse` rebuilds it. Pairs with
      * `restoreSparse`.
      *
-     * **Opt-in (#626 / ADR-0020).** Throws `DETERMINISM_DISABLED` unless the
-     * Store was constructed with `{ deterministic: true }` — the canonical
+     * **Opt-in.** Throws `DETERMINISM_DISABLED` unless the
+     * Store was constructed with `{ deterministic: true }`, the canonical
      * entity-index ordering is the determinism tax the flag gates. */
     snapshotSparse(): Uint8Array;
     /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
      * current sparse data (full-equality round-trip of membership + data), then
      * rebuild every relation's derived side indices: multi forward sets from the
      * relation section, and the reverse index for both cardinalities (exclusive
-     * from the just-restored sparse target field, multi from the rebuilt forward
+     * from the newly restored sparse target field, multi from the rebuilt forward
      * sets). The sparse components and relations must already be registered in
-     * the same order — restore carries data, not the registration (which is
+     * the same order, restore carries data, not the registration (which is
      * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
      * entity-index bounds, or frame length don't validate.
      *
-     * **Opt-in (#626 / ADR-0020).** Throws `DETERMINISM_DISABLED` unless the
-     * Store was constructed with `{ deterministic: true }`; paired with
+     * **Opt-in.** Throws `DETERMINISM_DISABLED` unless the
+     * Store was constructed with `{ deterministic: true }`. Paired with
      * `snapshotSparse`, which produces the canonical bytes restore consumes. */
     restoreSparse(bytes: Uint8Array): void;
+    /** The members and their values are the snapshot's now, so no record made
+     * before the restore names a write of theirs. */
+    private _resetSparseTicks;
     /**
      * Capture the full live world to one self-contained byte buffer that
-     * `restoreInto` can mount back onto a live, ticking world ("rewind a running
-     * world and keep ticking"). Three sections (see `resume.ts`): the dense SAB
-     * column bytes (`snapshotColumnStore`), the sparse + relation bytes
-     * (`snapshotSparse`), and the host-side bookkeeping the SAB omits — the world
-     * tick, the entity recycle free-list (in live order; no byte source, and its
+     * `restore` can mount back onto a live, ticking world ("rewind a running
+     * world and keep ticking"). Three sections, which the snapshots plugin
+     * frames: the dense SAB
+     * column bytes (`columnStoreBytesView`), the sparse + relation bytes
+     * (`snapshotSparse`), and the host-side bookkeeping the SAB omits, the world
+     * tick, the entity recycle free-list (in live order, no byte source, and its
      * order is load-bearing for byte-identical resume), the alive count, and each
-     * archetype's `length` / `enabledCount`.
+     * archetype's `length` and `enabledCount`.
      *
-     * **Opt-in (ADR-0020).** Throws `DETERMINISM_DISABLED` unless constructed with
-     * `{ deterministic: true }` — the sparse section rides the canonical-ordering
+     * **Opt-in.** Throws `DETERMINISM_DISABLED` unless constructed with
+     * `{ deterministic: true }`, the sparse section rides the canonical-ordering
      * surface and byte-identical resume is a determinism property. Pairs with
-     * `restoreInto`.
+     * `restore`.
      *
-     * **v1 scope.** Resources + events are NOT captured (resume requires
-     * resource-free per-tick state; events are tick-cleared). Change-detection /
-     * scheduler baselines (`changed()` queries) are likewise not captured — they
-     * are scheduling artifacts, never folded into `stateHash`. Take the snapshot
-     * at a tick boundary (between `update()`s). See the ADR. */
+     * Scope. It captures no resource and no event, because resume requires
+     * resource-free per-tick state and the tick clears events. It captures no
+     * change-detection baseline either, so a `changed()` query starts fresh.
+     * Those are scheduling artifacts, and never fold into `stateHash`. Take the
+     * snapshot at a tick boundary, between two `update()` calls. */
     snapshot(): Uint8Array;
     /**
      * Mount a `snapshot()` buffer onto this live world and leave it ready to keep
      * ticking. Fails closed on a malformed frame or a registration mismatch
-     * BEFORE any live state is touched (the archetype/component graph is rebuilt
-     * from code, not the snapshot — same contract as `restoreSparse`). On
+     * before any live state is touched (the archetype and component graph is rebuilt
+     * from code, not the snapshot, same contract as `restoreSparse`). On
      * success the world's dense + sparse state, entity allocator, and tick are
      * exactly the captured world's.
      *
      * Requires a world whose SAB-backed archetype set + column layout match the
      * snapshot's exactly (prewarm so the archetype set is stable) and the same
-     * entity-index capacity. **Opt-in (ADR-0020):** throws `DETERMINISM_DISABLED`
+     * entity-index capacity. **Opt-in:** throws `DETERMINISM_DISABLED`
      * unless `{ deterministic: true }`. See `snapshot()` for the v1 scope. */
-    restoreInto(bytes: Uint8Array): void;
-    /** Adopt a restored dense store (`SnapshotService.restoreInto`'s mount
+    restore(bytes: Uint8Array): void;
+    /** Adopt a restored dense store (the snapshot service's restore mount
      * step): swap the live backing, refresh every buffer-backed archetype's
      * views, recover the allocator high-water from the restored region, and
      * republish (the grow tail). Store-owned because it assigns
-     * `_columnStore` — the service never writes Store fields. */
+     * `_columnStore`, the service never writes Store fields. */
     private _mountRestoredDense;
-    /** Rebuild each SAB-backed archetype's host-side `length` / `enabledCount` /
-     * `_entityIds` after the dense backing was swapped in `restoreInto`. `length`
-     * + the per-row entity-id back-reference come from a scan of the restored
-     * entity-index region (which entity occupies which row); `enabledCount` comes
-     * from the captured host-state (the #577 partition boundary is positional only
-     * — it has no per-entity byte source). */
+    /** Rebuild each SAB-backed archetype's host-side `length`, `enabledCount`
+     * and `_entityIds` after `restore` swapped the dense backing. `length` and
+     * the per-row entity-id back-reference come from a scan of the restored
+     * entity-index region, which says what entity occupies what row.
+     * `enabledCount` comes from the captured host state, because the partition
+     * boundary is positional and has no per-entity byte source. */
     private _reconstructHostRows;
-    registerRelation(opts?: RelationOptions): RelationDef;
-    /** Number of registered relations. Visible to tests asserting the
-     * no-transition invariant alongside `archetype_count`. */
-    get relationCount(): number;
-    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
-    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
-    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
-    targetsOf(src: EntityID, def: RelationDef): EntityID[];
-    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
-    hasRelation(src: EntityID, def: RelationDef): boolean;
-    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
-    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
-    relationBackingSparseId(def: RelationDef): SparseComponentID;
-    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`) — see
-     * `RelationService.forEachRelationTargetMatch`. */
-    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
-    compactRelations(): number;
-    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
-    rootOf(src: EntityID, def: RelationDef): EntityID;
-    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
-    /** Second query-match path (#469 / ADR-0011): iterate entities matching a
+    /** Second query-match path: iterate entities matching a
      * dense mask **and** sparse-membership terms, invoking `cb` per entity.
-     * Yields `EntityID`s, not archetype spans — sparse members are scattered
+     * Yields `EntityID`s, not archetype spans, sparse members are scattered
      * across archetypes, so there is no SoA column to hand back. Driven by the
      * cheapest candidate set:
      *
@@ -835,65 +925,83 @@ export declare class Store implements ObserverHost, QueryHost {
      *    store.
      *  - **neither** → walk `denseArchetypes`' entity ids (dense-only fallback).
      *
-     * Only reached via `Query.forEachEntity`; dense `forEach` never consults
-     * the sparse stores, so dense-only queries are unaffected (#469 AC). */
-    _forEachSparseMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], denseArchetypes: readonly Archetype[], cb: (entityId: EntityID) => void, includeDisabled: boolean): void;
-    /** Fourth query-match path (#581): the matched set in hierarchy depth order
-     * (parents before children) — see `RelationService.forEachHierarchyMatch`. */
-    _forEachHierarchyMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+     * Only reached via `Query.forEachEntity`. Dense `forEach` never consults
+     * the sparse stores, so dense-only queries are unaffected. */
+    forEachSparseMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], cb: (entityId: EntityID) => void): void;
+    /** Fourth query-match path: the matched set in hierarchy depth order
+     * (parents before children), see `forEachHierarchyMatch` on the relation service. */
+    forEachHierarchyMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, cb: (entityId: EntityID) => void): void;
+    /** Third query-match path: the `(*, T)` wildcard, every source pointing at
+     * one target. `Query.forEachRelatedTo` is the seam the user reaches. */
+    forEachTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, cb: (entityId: EntityID) => void): void;
+    /** The sparse membership store a relation rides, which is how a query turns
+     * a `(R, *)` term into a sparse term. `api` names the query verb the user
+     * called, because `andRelation` and `notRelation` both land here. */
+    relationBackingSparseId(def: RelationDef, api: string): SparseComponentID;
+    private readonly _scratchTargetMask;
     addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): void;
     addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): void;
+    /** @internal, cold tail of `addComponent`: the entity already holds `def`
+     * (overwrite in place, no transition), or the (source, component) add edge
+     * has not been cached yet (first time this pair is seen, resolve, which
+     * plants the edge, then re-enter the hot body). Split out so the edge-hit
+     * path above stays a straight line with one holey-array probe. This runs at
+     * most once per (archetype, component) pair plus on in-place overwrites. */
+    private _addComponentCold;
     /** Add multiple components in one transition (resolves final archetype, then moves once).
      *
      * Final-mask resolve, not graph walk. The previous implementation called
-     * `archResolveAdd` once per entry, which threaded through every
-     * intermediate archetype on the path — and each unseen intermediate
+     * `_archResolveAdd` once per entry, which threaded through every
+     * intermediate archetype on the path, and each unseen intermediate
      * triggered a fresh `extendColumnStore` even though no entity ever lived
      * there. Computing the union mask up front and resolving once via
-     * `archGetOrCreateFromMask` collapses N-1 intermediate-archetype
-     * creations into zero for the batched case (#211 follow-up). The lazy
-     * single-mask path remains the same; this just avoids feeding it
+     * `_archGetOrCreateFromMask` collapses N-1 intermediate-archetype
+     * creations into zero for the batched case. The lazy
+     * single-mask path remains the same. This only avoids feeding it
      * archetypes the entity never visits.
      *
-     * #659 — composite-add edge cache. The final-mask resolve, unlike the
+     * Composite-add edge cache. The final-mask resolve, unlike the
      * single-add `edges[]` walk, re-pays a per-call `mask.hash()`, `ArchetypeGraph.lookup`
-     * (the Map-of-buckets + `equals` scan), and `getBatchTransitionMap` on
-     * every call — a ~2× gap vs a cached edge walk that the decomposition probe
-     * pinned on the two `Map.get`s, not the hash. So a repeated (source, added-
-     * set) add now resolves through `currentArch`'s composite-add cache: one
+     * (the Map-of-buckets + `equals` scan), and `transitionMapTo` on
+     * every call. That is much slower than a cached edge walk, and a probe put the
+     * cost on the two `Map.get` calls, and not on the hash. So a repeated (source,
+     * added-set) add now resolves through `currentArch`'s composite-add cache: one
      * `Map.get` on an exact packed key yields the target + transition map, and we
      * skip the union-mask build entirely. First call per key still resolves via
-     * the final-mask path below (no intermediate planting) and plants the edge.
-     * See docs/reports/bench/regressions/add-components-composite-edge.md. */
+     * the final-mask path below (no intermediate planting) and plants the edge. */
     addComponents(entityId: EntityID, entries: readonly TemplateEntryData[]): void;
-    /** Shared move+write tail of `addComponents` (#659): place the entity into
-     * the already-resolved `targetArch` — a `moveEntityFrom` along the cached
+    /** Shared move+write tail of `addComponents`: place the entity into
+     * the already-resolved `targetArch`, a `moveEntityFrom` along the cached
      * `map` when it has a row, else a fresh append (the rowless empty-archetype
-     * source ignores `map`) — then write every entry's fields. Both the
+     * source ignores `map`), then write every entry's fields. Both the
      * composite-edge-cache hit and the final-mask cold path funnel through here so
      * the placement logic lives once. */
     private _addComponentsInto;
     removeComponent(entityId: EntityID, def: ComponentDef): void;
+    /** @internal, cold tail of `removeComponent`: the entity doesn't hold `def`
+     * (no-op), or the (source, component) remove edge has not been cached yet.
+     * Mirror of `_addComponentCold`. Same depth-1 re-entry argument. */
+    private _removeComponentCold;
     /** Remove multiple components in one transition (resolves final archetype, then moves once).
      *
      * Final-mask resolve, not graph walk. Same rationale as `addComponents`
-     * above — the previous per-step path threaded `archResolveRemove`
+     * above, the previous per-step path threaded `_archResolveRemove`
      * once per def, which materialised every intermediate archetype on the
      * removal path. Computing the difference mask up front and resolving
      * once avoids planting N-1 intermediates the entity never lives in. */
     removeComponents(entityId: EntityID, defs: ComponentDef[]): void;
-    /** Total (POLISH_AUDIT #9): a dead/stale `entityId` returns `false` rather
-     * than throwing — a "has" probe is exactly what callers reach for to avoid
+    /** Total: a dead or stale `entityId` returns `false` rather
+     * than throwing, a "has" probe is exactly what callers reach for to avoid
      * touching dead entities, so it must be safe to ask. */
     hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
     /**
-     * Bulk add a component to ALL entities in the given archetype.
+     * Bulk add a component to all entities in the given archetype.
      * Uses TypedArray.set() for O(columns) instead of O(N×columns).
      * The archetype must not already contain this component.
      */
     batchAddComponent(src: ArchetypeID, def: ComponentDef, values?: Record<string, number>): void;
     /**
-     * Bulk remove a component from ALL entities in the given archetype.
+     * Bulk remove a component from all entities in the given archetype.
      * Uses TypedArray.set() for O(columns) instead of O(N×columns).
      * The archetype must contain this component.
      */
@@ -901,37 +1009,62 @@ export declare class Store implements ObserverHost, QueryHost {
     getEntityArchetype(entityId: EntityID): Archetype;
     getEntityRow(entityId: EntityID): number;
     /**
-     * Find all archetypes matching the given masks.
-     * Uses the inverted componentIndex to start from the component with the
-     * fewest archetypes, minimizing the number of superset checks.
+     * The row `resolveEntity` placed the entity at, the alloc-free second
+     * return value of a resolve, read immediately after the call. Same out-param
+     * pattern as `EntityAllocator.lastIndex` and `_moveResult`. Returning a
+     * `{ arch, row }` pair instead would allocate on every by-id read.
+     */
+    resolvedRow: number;
+    /**
+     * (archetype, row) for a by-id access, derived from one index computation.
+     *
+     * `getEntityArchetype` and `getEntityRow` are each one line, and every by-id
+     * caller needs both, so the pair cost two derivations of the same packed
+     * index and two call frames to read two elements of two parallel arrays
+     * addressed identically. This is that pair, fused: index once, publish the
+     * row on `resolvedRow`, return the archetype.
+     *
+     * The two single-purpose accessors stay above, tests reach for one half at a
+     * time, but no runtime path uses them in a pair any more.
+     */
+    resolveEntity(entityId: EntityID): Archetype;
+    /**
+     * Build the `at(entity)` binder a `ComponentCursor` repoints itself through
+     * (ref.ts). Handing the cursor a closure rather than the Store keeps the
+     * mutation surface out of a value that user code holds onto.
+     *
+     * `stampTick` distinguishes the two variants once, here, instead of per
+     * `at()`: a mutable cursor bumps the component's change tick on every
+     * repoint (matching `ctx.ref`), a read-only one never does.
+     *
+     * The access check lives here, in the binder, and not only at the call that
+     * creates the cursor. A cursor is made one time and then kept, so it outlives
+     * the span that made it. A cursor made at host level writes an undeclared
+     * component when a system body uses it, because no system is active at
+     * creation and the check there passes. A `ctx.cursor` that a system stores in
+     * an outer variable does the same in the next system. Both slip
+     * past a check that only runs at creation. `at()` is the point of use, so the
+     * check belongs on it. The creation-site check stays as well: it fails early,
+     * and its stack names the line that made the cursor.
+     */
+    cursorBinder(def: ComponentHandle, stampTick: boolean): CursorBinder;
+    /** A component's field names in schema order, the cursor prototype key and
+     * ordinal source (ref.ts). One array per component, owned by its meta. */
+    componentFieldNames(def: ComponentHandle): readonly string[];
+    /**
+     * Find all archetypes matching the given masks. Delegates to
+     * `QueryRegistry`, which starts the superset scan from the smallest
+     * component bucket. Query mint path only.
      */
     getMatchingArchetypes(required: BitSet, excluded?: BitSet, anyOf?: BitSet): readonly Archetype[];
     /**
-     * Register a live query. Returns a mutable Archetype[] that this Store will
-     * push newly-created matching archetypes into, keeping the query always up-to-date.
+     * Register a live query. Returns a mutable Archetype[] that the registry
+     * pushes newly-created matching archetypes into, keeping the query always
+     * up-to-date.
      */
     registerQuery(include: BitSet, exclude?: BitSet, anyOf?: BitSet): Archetype[];
     updateQueryRef(result: Archetype[], query: Query<any>): void;
     get archetypeCount(): number;
-    registerEvent<S extends EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
-    emitEvent(def: EventDef<any>, values: Record<string, number>): void;
-    emitSignal(def: EventDef<EmptyEventSchema>): void;
-    getEventReader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
-    clearEvents(): void;
-    /** `DEV`-only mid-update emit detection — see
-     * `EventRegistry.devBufferedEventCount`. */
-    _devBufferedEventCount(): number;
-    registerEventByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
-    getEventDefByKey(key: symbol): EventDef<any>;
-    hasEventKey(key: symbol): boolean;
-    private readonly resources;
-    registerResource(key: symbol, value: unknown): void;
-    getResource(key: symbol): unknown;
-    setResource(key: symbol, value: unknown): void;
-    /** Fails closed on a missing key; the present → absent → present
-     * lifecycle (#798) — see `ResourceRegistry.remove`. */
-    removeResource(key: symbol): void;
-    hasResource(key: symbol): boolean;
+    private readonly _resources;
 }
-export {};
 //# sourceMappingURL=store.d.ts.map