@oasys/oecs 0.5.2 → 0.5.4

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

@@ -1,4 +1,5 @@
 import { EntityID } from './entity.js';
+import { CursorBinder } from './ref.js';
 import { FrameTraceSink } from './frame_trace.js';
 import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component.js';
 import { SparseComponentDef, SparseComponentID } from './sparse_store.js';
@@ -21,14 +22,14 @@ export interface ComponentMeta {
     obsAdd: boolean;
     /** Has an onRemove observer — collect effective removes for this component. */
     obsRem: boolean;
-    /** Has an onDisable observer (#677) — collect effective disables for this
+    /** Has an onDisable observer — collect effective disables for this
      * component at the toggle drain. */
     obsDisable: boolean;
-    /** Has an onEnable observer (#677) — collect effective enables for this
+    /** Has an onEnable observer — 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). */
+     * (the opt-in dirty list). */
     trackDirty: boolean;
 }
 /**
@@ -45,13 +46,13 @@ export interface StructuralObserverEvents {
     remComp: number[];
     remEid: number[];
     remLen: number;
-    /** Effective disable events (#677) — collected during the toggle drain
+    /** Effective disable events — 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. */
+    /** Effective enable events, symmetric with the disable arrays. */
     enaComp: number[];
     enaEid: number[];
     enaLen: number;
@@ -75,14 +76,14 @@ 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
+/** A resolved template — 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. */
+ * pass. */
 export interface Template<Defs extends readonly ComponentDef[] = readonly ComponentDef[]> {
     readonly archetypeId: ArchetypeID;
     readonly flatValues: number[];
@@ -95,13 +96,13 @@ 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. */
     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. */
@@ -111,29 +112,29 @@ export interface StoreOptions {
      * 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).
+    /** 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. */
     entityIndexCapacity?: number;
-    /** Consumer-declared SAB regions (#623), forwarded verbatim to
+    /** 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. */
     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
+     * seam). De-welded from the engine ABI so a manifest edit doesn't
      * drift an engine golden. */
     bindingsRegionBytes?: number;
-    /** Opt into the **determinism surface** (#626 / ADR-0020). Default `false`.
+    /** Opt into the **determinism surface**. Default `false`.
      * Gates the three methods that fold/serialize state in canonical (sorted)
      * order: `stateHash`, `snapshotSparse`, `restoreSparse`. When `false`
      * those throw `DETERMINISM_DISABLED` — the canonical-ordering tax (sparse
@@ -141,7 +142,7 @@ export interface StoreOptions {
      * 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
      * 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. */
@@ -164,7 +165,7 @@ export declare class Store implements ObserverHost, QueryHost {
     private readonly _deferred;
     private readonly _snapshots;
     _tick: number;
-    /** Per-world frame-trace sink (ADR-0030), installed via `ECS.setTrace`.
+    /** 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
@@ -172,7 +173,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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/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;
@@ -184,14 +185,14 @@ export declare class Store implements ObserverHost, QueryHost {
     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). */
+     * previously-public field. */
     setStructuralObserverHook(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
+    /** 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
@@ -206,7 +207,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * (`flushStructural`/`flushDestroyed` 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). */
+     * phases' `ctx.flush` skip the descriptor walk entirely. */
     private _rowCountsDirty;
     /** Monotonic counter bumped by every membership-changing path (immediate
      * `addComponent(s)`, `removeComponent(s)`, `destroyEntity`,
@@ -214,7 +215,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * `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
+     * reuses its cached non-empty list. 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
@@ -229,45 +230,45 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+    /** 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
      * 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
+     * options object (adds `bufferAllocator` and
      * `onBufferResized` 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
+    /** 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. */
     private readonly _regions;
-    /** Byte size of the opt-in sim-bindings region (#625). 0 ⇒ no region (the
+    /** 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/extend path. */
     private readonly _bindingsRegionBytes;
-    /** Determinism opt-in (#626 / ADR-0020). When `false` (the default), the
+    /** Determinism opt-in. 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
+     * sort. Memory-safety invariants (the in-place allocator) and the
      * `enabled_count` partition are unaffected — they hold regardless. */
     private readonly _deterministic;
-    /** Whether the determinism surface is enabled (#626). `false` ⇒ `stateHash`
+    /** Whether the determinism surface is enabled. `false` ⇒ `stateHash`
      * / `snapshotSparse` / `restoreSparse` throw `DETERMINISM_DISABLED`. */
     get deterministic(): boolean;
     /** Guard the canonical-ordering determinism surface. Throws
@@ -277,11 +278,11 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+    /** Reject `f32`/`f64` fields on a `deterministic: true` world at registration.
+     * 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
+     * determinism opt-in 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
@@ -306,7 +307,7 @@ export declare class Store implements ObserverHost, QueryHost {
     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
+     * generic, de-gamed replacement 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`. */
@@ -315,16 +316,16 @@ export declare class Store implements ObserverHost, QueryHost {
      * `null` when absent. Carries the live `buffer`/`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/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` /
      * `growColumnStore` are the only other writers of `row_count`, and they
      * 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)
+     * off `arch_hdr.row_count` (every `tick_*` export)
      * read those stale bytes and silently skip the just-spawned rows.
      *
      * Lockstep walk: SAB descriptors are written by `extendColumnStore` in
@@ -333,10 +334,10 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * Gated by `_rowCountsDirty` — mutation paths
      * (`flushStructural`, `flushDestroyed`, immediate `destroyEntity`,
      * `addComponent(s)`, `removeComponent(s)`) set the flag; this method
      * clears it. Read-only phases that flush only to drain empty buffers
@@ -344,12 +345,11 @@ export declare class Store implements ObserverHost, QueryHost {
     publishRowCountsToDescriptor(): 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
+     * **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
@@ -364,11 +364,11 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * **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, ~4× faster than the per-
-     * byte loop it replaces. Trailing 0–3 tail bytes (only possible for
+     * digest with the same equality semantics, and much quicker 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
      * 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
@@ -381,7 +381,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * processes on the same architecture (which is all `replay_match`
      * needs — 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. */
@@ -391,8 +391,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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)
+     * 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
@@ -404,7 +403,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * `ArchetypeGraph.getOrCreateFromMask`. */
     private archGetOrCreateFromMask;
     /** Bulk variant of `archGetOrCreateFromMask` — one `extendColumnStore`
-     * call for the whole batch (Phase C prewarm, #213). See
+     * call for the whole batch (the prewarm pass). See
      * `ArchetypeGraph.createManyFromMasks`. */
     archCreateManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
     /** Snapshot every existing archetype's SAB rows, call `extendColumnStore`
@@ -435,11 +434,11 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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). */
+     * 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
@@ -475,7 +474,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * With no `delete`/`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
@@ -488,38 +487,65 @@ 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
+     * 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
      *     `> 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.)
+     *     postMessage decode applies.)
      *   - **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
+     * `entityArchetype`. 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 just needs "something moved"); bumps the query-dirty
+     * epoch only on a `length` 0/non-zero crossing, 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
+     * A shrink does **not** need the `enabledCount` crossing test: 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`
@@ -530,29 +556,29 @@ export declare class Store implements ObserverHost, QueryHost {
      * **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. */
+     * An earlier change added an `if (registeredQueries.length === 0) return;`
+     * gate to skip the bump for no-query workloads. The bench showed a large
+     * regression of the mutation churn loop, because the extra statement pushed
+     * the function past V8's per-call inlining budget. The gate is no longer in
+     * the code. Do a bench run before you merge a change here. Code review
+     * alone is not sufficient. */
     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
      * 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
+     * so the `preLen` test alone (the earlier proxy, valid only while
+     * `enabledCount === length`) misses it and a cached default query keeps a stale
      * `_nonEmpty` 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
+     * here too; this is bench-verified). 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,7 +587,7 @@ 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
+    /** Dirty bookkeeping for an enable/disable toggle. `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
@@ -580,7 +606,7 @@ export declare class Store implements ObserverHost, QueryHost {
     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
+     * 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;
@@ -594,12 +620,12 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * `_onArchLenChange` 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/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. */
     disableEntityDeferred(id: EntityID): void;
@@ -610,13 +636,13 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * 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
+     * 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;
@@ -631,7 +657,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
@@ -647,7 +673,7 @@ export declare class Store implements ObserverHost, QueryHost {
     /** 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*` /
+     *; the batch appliers it drives are the `_flush*` /
      * `_drainDestroyed` methods below. */
     flushStructural(): void;
     /** Batch-apply all deferred component additions. */
@@ -657,13 +683,13 @@ export declare class Store implements ObserverHost, QueryHost {
     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
+     * `_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). */
+     * dedup bit was clear (the dirty 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
@@ -681,7 +707,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * per-archetype change tick (free; no write-path cost). */
     _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
@@ -694,16 +720,16 @@ export declare class Store implements ObserverHost, QueryHost {
     /** 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). */
+     * field_id)` pairs across the WASM FFI. */
     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. */
     sparseLabel(sid: number): string;
-    /** Allocate the backing sparse store WITHOUT the #777 float guard, for
+    /** 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
@@ -731,11 +757,11 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * 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
+     * **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;
@@ -749,7 +775,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * **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;
@@ -763,7 +789,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * order is load-bearing for byte-identical resume), the alive count, and each
      * archetype's `length` / `enabledCount`.
      *
-     * **Opt-in (ADR-0020).** Throws `DETERMINISM_DISABLED` unless constructed with
+     * **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`.
@@ -784,7 +810,7 @@ export declare class Store implements ObserverHost, QueryHost {
      *
      * 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
@@ -797,7 +823,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * `_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
+     * from the captured host-state (the partition boundary is positional only
      * — it has no per-entity byte source). */
     private _reconstructHostRows;
     registerRelation(opts?: RelationOptions): RelationDef;
@@ -820,7 +846,7 @@ export declare class Store implements ObserverHost, QueryHost {
     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
      * across archetypes, so there is no SoA column to hand back. Driven by the
@@ -836,13 +862,20 @@ export declare class Store implements ObserverHost, QueryHost {
      *  - **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). */
+     * the sparse stores, so dense-only queries are unaffected. */
     _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
+    /** Fourth query-match path: 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;
     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
@@ -851,22 +884,21 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+     * creations into zero for the batched case. The lazy
      * single-mask path remains the same; this just 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
+     * 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
+    /** 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
@@ -874,6 +906,10 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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`
@@ -882,7 +918,7 @@ export declare class Store implements ObserverHost, QueryHost {
      * 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
+    /** Total: a dead/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;
@@ -900,6 +936,49 @@ export declare class Store implements ObserverHost, QueryHost {
     batchRemoveComponent(src: ArchetypeID, def: ComponentDef): void;
     getEntityArchetype(entityId: EntityID): Archetype;
     getEntityRow(entityId: EntityID): number;
+    /**
+     * 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 (where no system is
+     * active, and the check at creation therefore passes) writes an undeclared
+     * component when a system body uses it, and 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.
      * Uses the inverted componentIndex to start from the component with the
@@ -929,7 +1008,7 @@ export declare class Store implements ObserverHost, QueryHost {
     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`. */
+     * lifecycle — see `ResourceRegistry.remove`. */
     removeResource(key: symbol): void;
     hasResource(key: symbol): boolean;
 }