@oasys/oecs 0.4.0 → 0.5.1

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

@@ -0,0 +1,937 @@
+import { EntityID } from './entity.cjs';
+import { FrameTraceSink } from './frame_trace.cjs';
+import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component.cjs';
+import { SparseComponentDef, SparseComponentID } from './sparse_store.cjs';
+import { RelationDef, RelationOptions } from './relation.cjs';
+import { EmptyEventSchema, EventDef, EventReader, EventShape } from './event.cjs';
+import { BitSet, TypedArrayTag } from '../../type_primitives/index.cjs';
+import { Archetype, ArchetypeID } from './archetype.cjs';
+import { Query, QueryHost } from './query.cjs';
+import { ObserverHost } from './observer.cjs';
+import { InPlaceBufferAllocator, ColumnStoreRegionHandle, StoreRegionSpec, ColumnStore } from '../store/index.cjs';
+import { ECSMemoryCapContext } from './ecs_memory.cjs';
+export interface ComponentMeta {
+    /** Optional debug name from `registerComponent(schema, { name })` —
+     * diagnostic messages only, never behaviour. */
+    name?: string;
+    fieldNames: string[];
+    fieldIndex: Record<string, number>;
+    fieldTypes: TypedArrayTag[];
+    /** Has an onAdd observer — collect effective adds for this component. */
+    obsAdd: boolean;
+    /** Has an onRemove observer — collect effective removes for this component. */
+    obsRem: boolean;
+    /** Has an onDisable observer (#677) — collect effective disables for this
+     * component at the toggle drain. */
+    obsDisable: boolean;
+    /** Has an onEnable observer (#677) — collect effective enables for this
+     * component at the toggle drain. */
+    obsEnable: boolean;
+    /** Has a per-entity onSet observer — record dirty rows on the write path
+     * (the ADR-0012 opt-in dirty list). */
+    trackDirty: boolean;
+}
+/**
+ * Effective `(component, entity)` structural events for one fixed-point round,
+ * collected during `_flushAdds` / `_flushRemoves` and handed to the observer
+ * dispatch hook. Flat parallel arrays, count-bounded (`*_len`), reused across
+ * rounds — never reallocated in the flush. This is a scheduling artifact: it is
+ * NOT part of `stateHash` or snapshot. See `observer.ts`.
+ */
+export interface StructuralObserverEvents {
+    addComp: number[];
+    addEid: number[];
+    addLen: number;
+    remComp: number[];
+    remEid: number[];
+    remLen: number;
+    /** Effective disable events (#677) — collected during the toggle drain
+     * (`_flushToggles`), one per `(component, entity)` of each net-disabled
+     * entity's mask. Empty on a structural (add/remove/destroy) round. */
+    disComp: number[];
+    disEid: number[];
+    disLen: number;
+    /** Effective enable events (#677), symmetric with the disable arrays. */
+    enaComp: number[];
+    enaEid: number[];
+    enaLen: number;
+}
+/** Runtime shape of one template / `addComponents` entry: a def plus optional
+ * field values (omitted fields zero-fill). The public authoring surface is
+ * callable-bundle varargs, schema-checked per item by `StrictBundles`
+ * (component.ts); the `ECS` facade normalizes those bundles into this erased
+ * array before calling the store, so the store stays schema-agnostic. */
+type TemplateEntryData = {
+    readonly def: ComponentDef;
+    readonly values?: Readonly<Record<string, number>>;
+};
+/** 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 implements ObserverHost, QueryHost {
+    private readonly entityAllocator;
+    private readonly componentMetas;
+    private componentCount;
+    private readonly sparseStores;
+    /** Debug names parallel to `sparseStores` — diagnostics only. */
+    private readonly sparseNames;
+    private readonly relationService;
+    private readonly events;
+    private readonly archGraph;
+    private readonly registeredQueries;
+    private emptyArchetypeId;
+    private entityArchetype;
+    private entityRow;
+    private readonly _deferred;
+    private readonly _snapshots;
+    _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 via `setStructuralObserverHook` — dispatches a round's collected
+     * events to the observer registry (ordering + callbacks), which may enqueue
+     * further structural ops. */
+    private _structuralObserverHook;
+    /** Install the structural-observer dispatch hook (called once by `ECS`
+     * during construction) — the named seam replacing direct writes to the
+     * previously-public field (M1). */
+    setStructuralObserverHook(fn: (ev: StructuralObserverEvents) => void): void;
+    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 `ArchetypeGraph.install`).
+     * Read by `Query._nonEmpty()` via `QueryResolver._getQueryDirtyEpoch`
+     * — a query whose stored `_lastSeenEpoch` matches the current epoch
+     * reuses its cached non-empty list (#327). Replaces the previous walk
+     * over `registeredQueries` that wrote one dirty bit per query per
+     * mutation; 5000 startup adds × Q queries used to be 5000×Q writes,
+     * now it's 5000 integer increments. Public so ECS can forward through
+     * its `QueryResolver` impl; not part of the user-facing API. */
+    _queryDirtyEpoch: number;
+    private readonly initialCapacity;
+    private readonly _scratchTargetMask;
+    private _columnStore;
+    /** 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.archGraph.archetypes`. Iterating that array
+     * once, skipping non-SAB entries, and advancing an `archAddr` cursor
+     * by the descriptor's `column_count` lets us write `row_count` without
+     * the throwaway `Map<archId, length>` the previous version allocated
+     * on every call (#323). Cheap: descriptor-region seeks only, no column
+     * 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 — see
+     * `ArchetypeGraph.getOrCreateFromMask`. */
+    private archGetOrCreateFromMask;
+    /** Bulk variant of `archGetOrCreateFromMask` — one `extendColumnStore`
+     * call for the whole batch (Phase C prewarm, #213). See
+     * `ArchetypeGraph.createManyFromMasks`. */
+    archCreateManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
+    /** Snapshot every existing archetype's SAB rows, call `extendColumnStore`
+     * once with `newSpecs`, then refresh every pre-existing SAB-backed
+     * Archetype's TypedArray views. The single `existing` snapshot is the
+     * key win in the bulk variant — single-mask creation rebuilds it per
+     * call (i.e. N times for N new archetypes). */
+    private _archExtendStoreWithNewSpecs;
+    /** Materialise the `Archetype` object for a freshly-minted graph node —
+     * binds the graph's topology to THIS store's column backing and grow
+     * handler (`ArchetypeGraphHost.materialize`). Store-owned so the graph
+     * never touches `_columnStore`. */
+    private _materializeArchetype;
+    /** Push a newly-installed archetype into every registered query whose masks
+     * it satisfies (`ArchetypeGraphHost.fanIntoQueries`; the query registry
+     * stays on Store). No epoch bump — see the note in `ArchetypeGraph.install`. */
+    private _fanIntoQueries;
+    /** Resolve "add component_id to archetype_id" → target ArchetypeID (edge-cached). */
+    private archResolveAdd;
+    /** Resolve "remove component_id from archetype_id" → target ArchetypeID (edge-cached). */
+    private archResolveRemove;
+    createEntity(): EntityID;
+    /** Allocate an entity slot WITHOUT placing it in the empty archetype, for
+     * the template spawn paths. Returns the packed `EntityID`; the slot index
+     * is left in `entityAllocator.lastIndex`. Skips the empty-archetype
+     * membership write `createEntity` performs (the caller installs the real
+     * archetype + row). This *commits* the slot (bumps counts, stamps the
+     * generation so `isAlive` is already true), so the caller MUST have
+     * 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(entries: readonly TemplateEntryData[]): Template;
+    /** Resolve an override key to its flat column index, with the DEV guards
+     * for unknown and ambiguous field names; `-1` means skip (the production
+     * fallback where DEV would have thrown). */
+    private _resolveOverrideColumn;
+    /** Apply per-instance overrides to the freshly-spawned row. Each key is a
+     * field name resolved through the template's override index. */
+    private _applyOverrides;
+    /** Bulk variant of `_applyOverrides`: one `fill` per overridden column
+     * across the contiguous rows `[start, start + count)`. */
+    private _applyOverridesRange;
+    /** 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, overrides?: Record<string, number | undefined>): EntityID[];
+    /** Immediately destroy an entity, removing it from its archetype.
+     *
+     * With no `delete`/`clear` target-cleanup policy registered (the common
+     * case) this tears the one entity down and returns — no allocation. When a
+     * 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, the loop
+     * drains destroys itself via `_drainDestroyed`, so a re-entrant
+     * `ctx.flush()` from a callback no-ops (the guard lives in
+     * `DeferredCommandBuffer.flushDestroyed`) — otherwise it would collect
+     * into the shared `_obsEvents` scratch mid-dispatch and corrupt it. */
+    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;
+    /** Phase-boundary structural flush. The drain policy — no-observer fast
+     * path, observed fixed point (adds/removes → destroys → toggles),
+     * convergence guard, re-entrancy — lives in `DeferredCommandBuffer`
+     * (H1 step 4); the batch appliers it drives are the `_flush*` /
+     * `_drainDestroyed` methods below. */
+    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, name?: string): ComponentDef<S>;
+    /** `'Pos' (component 5)` when the component was registered with a debug
+     * name, else `component 5` — the label diagnostics interpolate. */
+    componentLabel(cid: number): string;
+    /** Return the field index assigned to `(def, fieldName)` at component
+     * registration. Indexes are insertion-order, zero-based, and stable for
+     * the lifetime of the ECS. Used by systems that pass `(component_id,
+     * field_id)` pairs across the WASM FFI (PR 3C / #231). */
+    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, 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
+     * 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;
+    /** Total, like `hasComponent` — `false` for a dead entity, never a throw. */
+    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
+    getSparseField(entityId: EntityID, def: SparseComponentDef, field: string): number;
+    setSparseField(entityId: EntityID, def: SparseComponentDef, field: string, value: number): void;
+    /** Drop all sparse data for a destroyed entity index so a recycled slot
+     * can't inherit it. Gated by the caller on `sparseStores.length > 0` to
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Adopt a restored dense store (`SnapshotService.restoreInto`'s mount
+     * step): swap the live backing, refresh every buffer-backed archetype's
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Store-owned because it assigns
+     * `_columnStore` — the service never writes Store fields. */
+    private _mountRestoredDense;
+    /** Rebuild each SAB-backed archetype's host-side `length` / `enabledCount` /
+     * `_entityIds` after the dense backing was swapped in `restoreInto`. `length`
+     * + the per-row entity-id back-reference come from a scan of the restored
+     * entity-index region (which entity occupies which row); `enabledCount` comes
+     * from the captured host-state (the #577 partition boundary is positional only
+     * — it has no per-entity byte source). */
+    private _reconstructHostRows;
+    registerRelation(opts?: RelationOptions): RelationDef;
+    /** Number of registered relations. Visible to tests asserting the
+     * no-transition invariant alongside `archetype_count`. */
+    get relationCount(): number;
+    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
+    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
+    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    hasRelation(src: EntityID, def: RelationDef): boolean;
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`) — see
+     * `RelationService.forEachRelationTargetMatch`. */
+    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    compactRelations(): number;
+    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
+    rootOf(src: EntityID, def: RelationDef): EntityID;
+    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
+    /** Second query-match path (#469 / ADR-0011): iterate entities matching a
+     * 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): 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;
+    /** 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()`, `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
+     * `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: readonly TemplateEntryData[]): 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;
+    /** Total (POLISH_AUDIT #9): 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;
+    /**
+     * 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 EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    emitEvent(def: EventDef<any>, values: Record<string, number>): void;
+    emitSignal(def: EventDef<EmptyEventSchema>): void;
+    getEventReader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
+    clearEvents(): void;
+    /** `DEV`-only mid-update emit detection — see
+     * `EventRegistry.devBufferedEventCount`. */
+    _devBufferedEventCount(): number;
+    registerEventByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    getEventDefByKey(key: symbol): EventDef<any>;
+    hasEventKey(key: symbol): boolean;
+    private readonly resources;
+    registerResource(key: symbol, value: unknown): void;
+    getResource(key: symbol): unknown;
+    setResource(key: symbol, value: unknown): void;
+    /** Fails closed on a missing key; the present → absent → present
+     * lifecycle (#798) — see `ResourceRegistry.remove`. */
+    removeResource(key: symbol): void;
+    hasResource(key: symbol): boolean;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map