@oasys/oecs 0.3.1 → 0.4.0

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

@@ -0,0 +1,1149 @@
+import { EntityID } from './entity';
+import { FrameTraceSink } from './frame_trace';
+import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component';
+import { SparseComponentDef, SparseComponentID } from './sparse_store';
+import { RelationDef, RelationOptions } from './relation';
+import { EmptyEventSchema, EventDef, EventReader, EventSchema } from './event';
+import { BitSet, TypedArrayTag } from '../../type_primitives';
+import { Archetype, ArchetypeID } from './archetype';
+import { Query } from './query';
+import { InPlaceBufferAllocator, ColumnStoreRegionHandle, StoreRegionSpec, ColumnStore } from '../store';
+import { ECSMemoryCapContext } from './ecs_memory';
+/**
+ * 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;
+}
+/** Extracts the schema out of a `ComponentDef` handle. */
+type SchemaOf<D extends ComponentDef> = D extends ComponentDef<infer S> ? S : ComponentSchema;
+/** One typed template entry: `values` is checked against the def's schema —
+ * a misspelled field is a compile error. Fields may be omitted (they default
+ * to 0), so the map is `Partial`. */
+export type TemplateEntry<D extends ComponentDef = ComponentDef> = {
+    readonly def: D;
+    readonly values?: Partial<FieldValues<SchemaOf<D>>>;
+};
+/** The entries tuple for `ECS.template` — each element's `values` is checked
+ * against its own `def`'s schema. */
+export type TemplateEntries<Defs extends readonly ComponentDef[]> = readonly [
+    ...{
+        [K in keyof Defs]: TemplateEntry<Defs[K]>;
+    }
+];
+/** Union of every field name owned by a component in `Defs` (distributes
+ * over the def list). */
+type TemplateFieldNames<Defs extends readonly ComponentDef[]> = Defs[number] extends ComponentDef<infer S> ? keyof S & string : never;
+/** Flat per-instance override map for `ECS.spawn`: any field of any
+ * component in the template, each optional. A misspelled field is a compile
+ * error (and still a `__DEV__` throw at runtime for untyped call sites). */
+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
+     * Store's flush loops hoist entity-index views across grows, so only
+     * in-place allocators may back one (ADR-0008) — 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
+     * 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. */
+    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
+     * 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
+     * `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
+     * `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. */
+    bindingsRegionBytes?: number;
+    /** Opt into the **determinism surface** (#626 / ADR-0020). 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
+     * `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
+     * 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
+     * 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. */
+    deterministic?: boolean;
+}
+export declare class Store {
+    private entityGenerations;
+    private entityHighWater;
+    private readonly entityFreeIndices;
+    private entityAliveCount;
+    private readonly componentMetas;
+    private componentCount;
+    private readonly sparseStores;
+    private readonly relations;
+    private _hasTargetCleanup;
+    private readonly eventChannels;
+    private readonly dirtyEventChannels;
+    private eventCount;
+    private readonly archetypes;
+    private readonly archetypeMap;
+    private nextArchetypeId;
+    private readonly componentIndex;
+    private readonly registeredQueries;
+    private emptyArchetypeId;
+    private entityArchetype;
+    private entityRow;
+    private readonly pendingDestroy;
+    private readonly pendingAddIds;
+    private readonly pendingAddDefs;
+    private readonly pendingAddValues;
+    private readonly pendingRemoveIds;
+    private readonly pendingRemoveDefs;
+    private readonly pendingToggleIds;
+    private readonly pendingToggleDisable;
+    _tick: number;
+    /** Per-world frame-trace sink (ADR-0030), 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;
+    private _structuralObserverCount;
+    /** Count of components with any onDisable/onEnable observer (#677). While 0
+     * (with `_structuralObserverCount` also 0), `flushStructural` takes the
+     * byte-for-byte fast path and the toggle drain skips event collection. */
+    private _toggleObserverCount;
+    /** Reused effective-event scratch for the current flush round. */
+    private readonly _obsEvents;
+    /** Installed by `ECS` — dispatches a round's collected events to the observer
+     * registry (ordering + callbacks), which may enqueue further structural ops. */
+    _structuralObserverHook: ((ev: StructuralObserverEvents) => void) | null;
+    /** Re-entrancy guard for the observed fixed-point loop. An observer callback
+     * must enqueue (add/remove) and let the loop settle it — calling `ctx.flush()`
+     * from inside a callback would re-enter `flushStructural` and corrupt the
+     * shared event scratch. The guard turns that nested call into a no-op; the
+     * outer loop drains whatever the callback queued. */
+    private _flushingStructural;
+    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
+     * `_flushToggles` emit one event per *net* transition (disable→enable→disable
+     * 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. */
+    private readonly _toggleInitial;
+    _anyDirtyTracked: boolean;
+    private readonly _dirtyTrackedCids;
+    private readonly _dirtyLists;
+    private readonly _dirtyMarks;
+    /** Set by any path that changes a SAB-backed archetype's live row count
+     * (`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). */
+    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 `archInstall`).
+     * 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;
+    private readonly _hierarchyRadixOut;
+    private readonly _hierarchyRadixC0;
+    private readonly _hierarchyRadixC1;
+    private _columnStore;
+    /** Single-slot Uint32Array view over the entity-index region's `length`
+     * header field. `createEntity`'s hot path writes `entityHighWater`
+     * here on every high-water bump; using a pre-built typed-array view
+     * skips the DataView lookup + setUint32 dispatch that #368 traced to
+     * ~25 ns/op on `frame_loop_focused: createEntity` (closes the
+     * post-#361 gap to oecs entirely). Rebuilt on SAB resize. */
+    private _entityIndexLengthView;
+    /** 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) */
+    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
+     * 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). */
+    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
+     * 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
+     * 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
+     * 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
+     * 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
+     * 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. */
+    private readonly _deterministic;
+    /** Whether the determinism surface is enabled (#626). `false` ⇒ `stateHash`
+     * / `snapshotSparse` / `restoreSparse` throw `DETERMINISM_DISABLED`. */
+    get deterministic(): boolean;
+    /** Guard the canonical-ordering determinism surface. Throws
+     * `DETERMINISM_DISABLED` when determinism wasn't opted into, naming the
+     * method so the caller knows to pass `{ deterministic: true }`. Always on
+     * (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;
+    /** 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. */
+    private _refreshEntityIndexViews;
+    /** Centralised "SAB was just 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
+     * 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`. */
+    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
+     * `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) */
+    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` /
+     * `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)
+     * read those stale bytes and silently skip the just-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.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
+     * I/O.
+     *
+     * Gated by `_rowCountsDirty` (#324) — 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
+     * pay nothing. */
+    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.
+     *
+     * **Sparse coverage (#470).** 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
+     * (`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
+     * 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
+     * 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
+     * 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
+     * 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).
+     *
+     * **Opt-in (#626 / ADR-0020).** 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)
+     *
+     * 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. */
+    entityIdAtRow(archetypeId: number, row: number): EntityID;
+    /**
+     * Find or create an archetype for the given component mask.
+     * Also updates the componentIndex and pushes into matching registered queries.
+     *
+     * Hot single-mask path. The bulk batched variant — used by Phase C
+     * pre-warming at `world.startup()` — is `archCreateManyFromMasks`;
+     * see #213 / `ECS.startup()` for how it gets called and why.
+     */
+    private archGetOrCreateFromMask;
+    /**
+     * Bulk variant of `archGetOrCreateFromMask` — Phase C of issue #213.
+     *
+     * Given a set of masks, creates Archetypes for the ones not already
+     * planted, in a SINGLE `extendColumnStore` call (instead of one per
+     * archetype). Single-mask creation is O(N) in archetypes-so-far because
+     * the extend has to copy every existing archetype's live rows forward;
+     * N such calls compound to O(N²). Batching collapses the per-archetype
+     * setup-and-copy down to one pass — the per-startup cost the design doc
+     * §5.2 calls out as "O(N²) → O(N)" for in-tree systems whose archetype
+     * set is known at registration time via `spawns` + `transitions`.
+     *
+     * Masks already in the map are skipped. Returns the resolved
+     * `ArchetypeID` per input mask in input order — callers that don't need
+     * the ids can ignore the return value.
+     */
+    archCreateManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
+    /** Hash-bucketed mask → ArchetypeID lookup; null when the mask isn't planted. */
+    private archLookup;
+    /** Walk the mask's set bits and resolve each non-tag component to its
+     * layout. Used by both single and bulk archetype-create paths. */
+    private archBuildLayouts;
+    /** 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` for `id`, register in the archetype map +
+     * component index, and fan into any matching registered queries.
+     *
+     * Clones `mask` before storing — callers may pass scratch BitSets that
+     * they intend to reuse (e.g. `addComponents` / `removeComponents`'s
+     * `_scratchTargetMask`). The Archetype and the archetypeMap bucket
+     * both keep references long-term, so the clone is required for
+     * correctness — and is the previously-implicit guarantee made by the
+     * mask-allocating callers (`copyWithSet`, `copyWithClear`, etc.). */
+    private archInstall;
+    /** Resolve "add component_id to archetype_id" → target ArchetypeID. Caches the edge. */
+    private archResolveAdd;
+    /** Resolve "remove component_id from archetype_id" → target ArchetypeID. Caches the edge. */
+    private archResolveRemove;
+    /** Cache a bidirectional add/remove edge between two archetypes. */
+    private archCacheEdge;
+    createEntity(): EntityID;
+    /** Slot index of the entity allocated by the most recent `_allocEntity`
+     * call. Read immediately after the call (alloc-free out-param). */
+    private _spawnIndex;
+    /** 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 `_spawnIndex`. Mirrors `createEntity`'s allocator but skips the
+     * empty-archetype membership write (the caller installs the real archetype
+     * + row). Kept separate from `createEntity` so that hot path stays inline
+     * (#368). This *commits* the slot (bumps counts, stamps the 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). */
+    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
+     * 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
+     * high-water headroom. */
+    private _ensureEntityIndexCapacity;
+    /** Resolve 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
+     * one component, which a flat override cannot target). */
+    resolveTemplate<Defs extends readonly ComponentDef[]>(entries: TemplateEntries<Defs>): Template<Defs>;
+    /** Apply per-instance overrides to the freshly-spawned row. Each key is a
+     * field name resolved through the template's override index. */
+    private _applyOverrides;
+    /** Spawn one entity directly into the template's archetype (zero archetype
+     * transitions). Writes the template defaults in a single append pass, then
+     * 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
+     * spawn order. */
+    spawnMany(p: Template, count: number): 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
+     * 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):
+     * 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`
+     * 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. */
+    destroyEntity(id: EntityID): void;
+    /** Tear a single entity out of its archetype, relation, and sparse stores,
+     * 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);
+     * `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
+     * 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.)
+     *   - **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).
+     */
+    isAlive(id: EntityID): boolean;
+    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
+     * 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
+     * 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
+     * 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
+     * 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.
+     *
+     * **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
+     * `(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
+     *     before and is non-zero now (`preEnabled === 0 && enabledCount !== 0`);
+     *     a disabled-row append leaves it 0 and correctly skips. The `enabledCount`
+     *     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`). */
+    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). */
+    disableEntity(id: EntityID): void;
+    /** Immediately enable an entity (idempotent). */
+    enableEntity(id: EntityID): void;
+    /** Whether `id` is currently disabled. A component-less entity is never
+     * 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
+     * current flush epoch (`Archetype._flushSeenEpoch`), its pre-length and
+     * pre-enabled-count recorded on first sight (`_flushPreLen` /
+     * `_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
+     * 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
+     * (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
+     * toggle performs would corrupt a `forEach` over that archetype if applied
+     * mid-system, so it is deferred like add/remove. */
+    disableEntityDeferred(id: EntityID): void;
+    enableEntityDeferred(id: EntityID): void;
+    /** Drain buffered enable/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
+     * 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
+     * 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. */
+    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
+     * 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
+     * `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.
+     *
+     * Re-entrancy: while the observed fixed point owns the flush
+     * (`_flushingStructural`), the loop drains destroys itself via
+     * `_drainDestroyed`, so a re-entrant `ctx.flush()` from a callback no-ops
+     * here — otherwise it would collect into the shared `_obsEvents` scratch
+     * mid-dispatch and corrupt it (mirrors the `flushStructural` guard). */
+    flushDestroyed(): void;
+    private _drainDestroyed;
+    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;
+    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
+     * 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;
+    /** 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;
+    /** Enabled live entities currently carrying `cid`, used by `yieldExisting` to
+     * replay onAdd on registration. Bounded by `enabled_count` (#677): 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
+     * registry radix-sorts. */
+    _collectEntitiesWithComponent(cid: number): EntityID[];
+    registerComponent<S extends Record<string, TypedArrayTag>>(schema: S): ComponentDef<S>;
+    /** 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). */
+    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`. */
+    registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S): SparseComponentDef<S>;
+    /** Allocate the backing sparse store WITHOUT the #777 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
+     * *arithmetic* rounding, which a target slot never undergoes). User schemas go
+     * through `registerSparseComponent`, which guards first. */
+    private _pushSparseStore;
+    private sparseStoreOf;
+    /** Add (or overwrite) a sparse component on an entity. No archetype
+     * 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;
+    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
+     * keep the destroy hot path free when sparse storage is unused. */
+    private _purgeSparse;
+    /** 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
+     * 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
+     * `restoreSparse`.
+     *
+     * **Opt-in (#626 / ADR-0020).** 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
+     * sets). The sparse components and relations must already be registered in
+     * 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
+     * `snapshotSparse`, which produces the canonical bytes restore consumes. */
+    restoreSparse(bytes: Uint8Array): void;
+    /** Rebuild every relation's derived side indices after the sparse stores have
+     * been restored. `restoreRelations` resets all relations, rebuilds the multi
+     * forward sets + their reverse edges from `relBytes`, and validates shape.
+     * The exclusive reverse index can't be carried in the bytes (it's derivable),
+     * so it's rebuilt here from the backing sparse store: every member row holds
+     * `(source index → target EntityID)`, which is exactly one reverse edge. */
+    private _rebuildRelationIndices;
+    /**
+     * 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
+     * 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
+     * `{ deterministic: true }` — the sparse section rides the canonical-ordering
+     * surface and byte-identical resume is a determinism property. Pairs with
+     * `restoreInto`.
+     *
+     * **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. */
+    snapshot(): Uint8Array;
+    /** Gather the host-side state a snapshot carries alongside the dense + sparse
+     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
+    private _collectHostState;
+    /**
+     * 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
+     * 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`
+     * unless `{ deterministic: true }`. See `snapshot()` for the v1 scope. */
+    restoreInto(bytes: Uint8Array): void;
+    /** Read-only validation of a `snapshotSparse` SECTION (the framed
+     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
+     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+     * sparse-stores sub-section without mutating. A relation-registration difference
+     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+     * differing relation set changes the sparse store count / schema. Throws
+     * `SparseRestoreError` on a mismatch. */
+    private _assertSparseSectionMatches;
+    /** 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). */
+    private _reconstructHostRows;
+    /** Register a relation kind. `exclusive` (the default) → one target per
+     * source, stored in a backing `{ target: f64 }` sparse component, so the
+     * forward index rides the sparse store and inherits query membership (#469),
+     * `stateHash` + snapshot/restore (#470) for free. `multi` → a set of
+     * targets per source, backed by a sparse tag for membership plus a side
+     * forward index the relation owns. The two cardinalities are mutually
+     * exclusive. `onDeleteTarget` selects the cleanup policy run when a target
+     * is destroyed — `delete` (cascade-destroy sources), `clear` (drop the link,
+     * sources survive), or `orphan` (default: leave it dangling, #473). See
+     * ADR-0011 and `relation.ts`.
+     *
+     * The backing sparse store is resolved and handed to the relation so it can
+     * drive forward/membership rows directly — the cardinality-specific
+     * interaction is `ExclusiveRelationStore` / `MultiRelationStore`'s, not a
+     * branch here (#498). */
+    registerRelation(opts?: RelationOptions): RelationDef;
+    private relationOf;
+    /** Number of registered relations. Visible to tests asserting the
+     * no-transition invariant alongside `archetype_count`. */
+    get relationCount(): number;
+    /** Add a `(R, tgt)` pair to `src`. No archetype transition. Exclusive:
+     * replaces any existing target (engine-enforced one-per-source), a no-op if
+     * `tgt` is already the target. Multi: adds `tgt` to the set, a no-op if
+     * already present. A dead `src` *or* `tgt` is caller error: it throws in
+     * `__DEV__` and is a no-op in production — symmetric, so a production build
+     * never links a reverse-index entry keyed by a destroyed handle (#495). */
+    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
+    /** Remove a `(R, tgt)` pair from `src`. No archetype transition. Exclusive:
+     * `tgt` is optional and the removal is a no-op when it names a target other
+     * than the current one. Multi: omitting `tgt` removes *all* of `src`'s
+     * targets; passing one removes just that pair (dropping membership when the
+     * set empties). */
+    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
+    /** The single target of `src` under an exclusive relation, or `undefined`.
+     * Throws in `__DEV__` on a multi-target relation (use `targetsOf`). */
+    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
+    /** All targets of `src` under `R` — one or zero for exclusive, the full set
+     * for multi — ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources that point at `tgt` under `R` (the reverse index), ascending by
+     * id; empty when none. */
+    sourcesOf(def: RelationDef, tgt: EntityID): EntityID[];
+    /** Whether `src` holds any pair under `R`. */
+    hasRelation(src: EntityID, def: RelationDef): boolean;
+    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
+     * (#472). Sources are emitted in **canonical entity-index order** (the #470
+     * determinism convention): exclusive relations ride the backing sparse
+     * store's `canonicalIndices`, multi relations ride the same
+     * `forEachCanonicalTargetSet` traversal `stateHash` / `snapshotRelations`
+     * use; a multi source's targets follow ascending by id. Empty when the
+     * relation holds no pairs. Cold path — allocates the result array (and, for
+     * multi, sorts each source's target set); not for per-tick use. The
+     * point-query forms are `targetOf` / `targetsOf`. */
+    pairsOf(def: RelationDef): [EntityID, EntityID][];
+    /** Every `(relation, source)` pointing at `tgt`, across **all** registered
+     * relation kinds — the `(*, T)` wildcard (#472). Walks the relation registry
+     * in id order (each relation's reverse index already returns sources
+     * ascending by id), so the result is ordered by relation id then source id.
+     * Empty when nothing targets `tgt`. The single-relation form is
+     * `sourcesOf(def, tgt)`. */
+    sourcesOfAny(tgt: EntityID): [RelationDef, EntityID][];
+    /** The backing sparse component id of relation `R` — the membership store a
+     * `(R, *)` wildcard term (`Query.withRelation`) drives through the shared
+     * sparse-match path. Exclusive relations back a `{ target: f64 }` sparse
+     * component, multi a tag; both carry per-source membership, so "has any
+     * `(R, *)` pair" is exactly membership in this store (including an
+     * orphan-dangling source, whose membership row persists — consistent with
+     * `pairsOf`). The def is engine-owned and never handed to callers; this hands
+     * the query builder only its erased id for the `sparseInclude` list. */
+    relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`): every source
+     * related to `target` under **any** relation, intersected with the query's
+     * dense mask + sparse require/exclude terms + the default enabled-row filter,
+     * each source yielded once. Unions `sourcesOf(R, target)` across every
+     * relation into a `Set` (dedup by full `EntityID` — a source related to `T`
+     * via two relations is yielded once), then sorts ascending: the cross-relation
+     * union has no inherent order, so one cold sort gives a deterministic,
+     * canonical `(*, T)` order matching `sourcesOf` / `sourcesOfAny` (which sort
+     * the same way). Cold/structural — not a per-tick hot loop over many targets.
+     * `sparseInclude`/`sparseExclude` carry both raw sparse terms and the backing
+     * stores of any composed `(R, *)` terms, so it intersects with them uniformly. */
+    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    /** Reclaim reverse-index memory: drop every relation's reverse entries whose
+     * **target** has been destroyed, returning the total dropped across all
+     * relations (#491). Under the default `orphan` policy a destroyed target
+     * leaves its reverse entry intact until each source re-targets or dies, so a
+     * long-lived source that orphan-points at a churn of short-lived targets and
+     * never re-targets accumulates dead-target keys without bound. This cold-path
+     * hook drops them on demand — call it at scene or snapshot boundaries.
+     *
+     * Purely a memory reclaim with no observable state change: forward links stay
+     * dangling (so `orphan`'s `targetOf`-returns-the-dead-handle contract is
+     * unchanged), `stateHash` is unaffected (the reverse index is derived, never
+     * folded), and the dropped entries are faithfully rebuilt by snapshot/restore
+     * from the surviving forward links (`_rebuildRelationIndices`). The only
+     * difference a caller can see is `sourcesOf(R, deadHandle)` going from the
+     * dangling sources to `[]` — both meaningless once the target is gone.
+     * No-op (returns 0) when no relations are registered. */
+    compactRelations(): number;
+    /** Walk exclusive relation `R` from `src` toward the root, returning the
+     * **up**-chain `[src, parent, grandparent, …, root]` (nearest-ancestor-first,
+     * inclusive of both endpoints). A source with no target returns `[src]`. The
+     * root is the first entity in the chain with no `R`-target, **or** a dangling
+     * dead target handle (see below). Throws `RELATION_MODE_MISMATCH` on a multi
+     * relation and `RELATION_CYCLE` on a cycle (both `__DEV__`-only; in production
+     * a cycle stops at the repeated node).
+     *
+     * **Dangling links terminate the chain.** Under the `orphan` policy a source
+     * keeps pointing at a destroyed target (a dead handle). The walk must *not*
+     * advance through such a handle: the backing store is keyed by entity
+     * **index**, so reading the dead handle's index would return whatever now
+     * occupies that recycled slot — splicing the chain onto an unrelated entity
+     * (the ABA the `EntityID`-keyed reverse index avoids for `cascadeOf`). So a
+     * dead next-hop is appended as the chain's (dangling) terminus and the walk
+     * stops; the caller can detect it with `isAlive`, exactly as `targetOf`
+     * returns a dead handle. */
+    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** The root of `src`'s exclusive-relation chain — the last entity of
+     * `ancestorsOf` (the one with no `R`-target). `src` itself when it has no
+     * target. If the chain ends in a dangling dead target handle (orphan policy),
+     * that handle is the root — `isAlive`-check the result if dangling links are
+     * possible. Same `__DEV__` guards as `ancestorsOf`. */
+    rootOf(src: EntityID, def: RelationDef): EntityID;
+    /** Walk exclusive relation `R` **down** from `root` over the reverse index,
+     * returning the subtree (including `root`) breadth-first — **parents before
+     * children** (the `cascade` order). Children of each node come from
+     * `sourcesOf` (ascending by id), so the traversal is deterministic. Throws
+     * `RELATION_MODE_MISMATCH` on a multi relation and `RELATION_CYCLE` on a cycle
+     * (both `__DEV__`-only; in production an already-visited node is skipped, so
+     * it never hangs). */
+    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
+    /** Purge a destroyed entity from the relation indices — its **source** role
+     * only: drop its forward target(s) and unlink it from every target's reverse
+     * set. The backing sparse membership row is dropped separately by
+     * `_purgeSparse`, so this must run *before* it (it reads the sparse target
+     * field for exclusive relations). The entity's **target** role is left
+     * intact: the reverse index is keyed by full `EntityID`, so a recycled slot
+     * never aliases the dead target's sources. The destroyed entity's **target**
+     * role is handled separately by `_cleanupRelationTargets` per each
+     * relation's `OnDeleteTarget` policy (#473). Gated by the caller on
+     * `relations.length > 0`. */
+    private _purgeRelations;
+    /** Apply each relation's `OnDeleteTarget` policy for a destroyed **target**
+     * `targetId` (#473). Walks the registry; for every relation whose reverse
+     * index has sources pointing at the dead target:
+     *
+     *  - **`delete`** — append each source to `cascade`; the caller destroys them
+     *    through the same path, so chains/trees cascade recursively. The sources'
+     *    own source-role purge (`_purgeRelations`) drops their forward link and
+     *    unlinks them from `targetId`'s reverse set, so no reverse entry leaks.
+     *  - **`clear`** — drop each source's link to the dead target in place via
+     *    `rs.unlink(src, targetId)` (exclusive drops the row; multi removes the
+     *    target from the set, dropping membership when it empties). Sources
+     *    survive — the cardinality bookkeeping is the relation's, not branched here.
+     *  - **`orphan`** — skipped (the link is left dangling; safe because the
+     *    reverse key carries the generation).
+     *
+     * `sourcesOf` returns a fresh snapshot, so mutating the reverse index while
+     * iterating is safe. Gated by the caller on `_hasTargetCleanup`, so the
+     * whole walk is skipped when no relation opts into a non-`orphan` policy. */
+    private _cleanupRelationTargets;
+    /** Second query-match path (#469 / ADR-0011): 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
+     * cheapest candidate set:
+     *
+     *  - **sparse require present** → walk the *smallest* required store's
+     *    `indices` (an upper bound on the result), filtering each by the other
+     *    required stores, the excluded stores, and the dense mask resolved from
+     *    the entity's own archetype. Independent of archetype count.
+     *  - **sparse exclude only** → walk `denseArchetypes` (already dense-mask-
+     *    matched and non-empty by the caller), skipping rows in any excluded
+     *    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): yield the matched entities — the exact
+     * `_forEachSparseMatch` intersection (dense mask + sparse require/exclude +
+     * the default enabled-row filter) — in canonical **hierarchy depth order** over
+     * exclusive relation `R`: depth ascending (parents before children), **entity
+     * index ascending within each depth band**. Entities deeper than `maxDepth`
+     * are skipped (`Infinity` = unbounded). Only reached via `Query.forEachEntity`
+     * on a query carrying a `.hierarchy(R)` term.
+     *
+     * `.hierarchy(R)` does not narrow the matched set — it reorders it — so an
+     * entity with no `R`-parent is a root (depth 0) and is yielded first. Depth is a
+     * structural property of the *full* tree (an ancestor outside the matched set
+     * still counts toward depth), computed by a memoised upward walk shared across
+     * the whole batch, so a shared/deep chain costs O(nodes), not O(nodes²).
+     *
+     * The canonical order is produced without a comparator sort (which the observer
+     * bench measured at 2–4× — `observer.ts`): (1) collect the matched ids via
+     * `_forEachSparseMatch`; (2) `radixSortByIndex` → entity-index ascending;
+     * (3) stable-bucket by depth — since the input is index-ascending and the bucket
+     * append is stable, each depth band stays index-ascending. Tuned for the
+     * motivating per-tick case (transform propagation): the radix scratch is reused
+     * instance state (`_hierarchy_radix_*`), so a per-tick pass churns no histograms;
+     * the working set (`matched` / `buckets` / `depthMemo` / `visiting`) is still
+     * allocated per call, as it must stay call-local for re-entrancy.
+     *
+     * Exclusive-only — a multi relation throws `RELATION_MODE_MISMATCH` in `__DEV__`
+     * (mirrors `cascadeOf` / `ancestorsOf`); a cycle is a loud `RELATION_CYCLE` in
+     * `__DEV__` and a safe break in production. */
+    _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;
+    /** Depth of entity index `idx` in the exclusive-relation tree backing `store`
+     * (root = 0), for `_forEachHierarchyMatch`. Memoised across the batch (`memo`),
+     * so a shared ancestor chain is walked once. Walks upward via the backing store's
+     * target field 0 (mirroring `ancestorsOf`), stopping at: a root (no target), an
+     * already-memoised node, or a dangling/dead parent (the child is then treated as
+     * a root — never advance through a recycled slot, the ABA `ancestorsOf` guards).
+     * `visiting` flags the nodes on the current upward path to catch a cycle —
+     * `RELATION_CYCLE` in `__DEV__`, treated as a root in production — and is emptied
+     * on the way back down so it can be reused for the next entity. */
+    private _hierarchyDepthOf;
+    addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): void;
+    addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): void;
+    /** 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
+     * 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
+     * archetypes the entity never visits.
+     *
+     * #659 — composite-add edge cache. The final-mask resolve, unlike the
+     * single-add `edges[]` walk, re-pays a per-call `mask.hash()`, `archLookup`
+     * (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
+     * `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. */
+    addComponents(entityId: EntityID, entries: {
+        def: ComponentDef;
+        values?: Record<string, number>;
+    }[]): void;
+    /** Shared move+write tail of `addComponents` (#659): 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
+     * 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;
+    /** 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`
+     * 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;
+    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    /**
+     * 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.
+     * Uses TypedArray.set() for O(columns) instead of O(N×columns).
+     * The archetype must contain this component.
+     */
+    batchRemoveComponent(src: ArchetypeID, def: ComponentDef): void;
+    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.
+     */
+    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.
+     */
+    registerQuery(include: BitSet, exclude?: BitSet, anyOf?: BitSet): Archetype[];
+    updateQueryRef(result: Archetype[], query: Query<any>): void;
+    get archetypeCount(): number;
+    registerEvent<S extends EventSchema>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    emitEvent(def: EventDef, values: Record<string, number>): void;
+    emitSignal(def: EventDef<EmptyEventSchema>): void;
+    getEventReader<S extends EventSchema>(def: EventDef<S>): EventReader<S>;
+    clearEvents(): void;
+    /** `__DEV__`-only: total events currently buffered across the dirty channels.
+     * `ECS.update` samples this either side of `dispatchSet` to assert an onSet
+     * observer emitted nothing — its emissions would be wiped by the tick-tail
+     * `clearEvents` and break the empty-channel-at-boundary invariant snapshot /
+     * restore relies on (#586). Walks only the dirty list, never the hot emit path. */
+    _devBufferedEventCount(): number;
+    private readonly eventKeyMap;
+    registerEventByKey<S extends EventSchema>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    getEventDefByKey(key: symbol): EventDef<any>;
+    hasEventKey(key: symbol): boolean;
+    private readonly resourceKeyMap;
+    registerResource(key: symbol, value: unknown): void;
+    getResource(key: symbol): unknown;
+    setResource(key: symbol, value: unknown): void;
+    removeResource(key: symbol): void;
+    hasResource(key: symbol): boolean;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map