@oasys/oecs 0.5.4 → 0.6.0

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

@@ -1,140 +1,145 @@
 import { Template, TemplateOverrides } from './store.cjs';
 import { FrameTraceSink } from './frame_trace.cjs';
-import { ObserverHandle, EntitySetObserverConfig, ArchetypeSetObserverConfig, StructuralObserverConfig } from './observer.cjs';
-import { ColumnStore, ColumnStoreRegionHandle, StoreRegionSpec } from '../store/index.cjs';
-import { ECSRelations, ECSEvents, ECSResources, ECSSnapshots } from './facades.cjs';
-import { SCHEDULE, SystemEntry, SystemSet, SystemSetConfig } from './schedule.cjs';
+import { ColumnStore, ColumnStoreRegionHandle } from '../store/index.cjs';
+import { ECSResources, ECSSnapshots } from './facades.cjs';
+import { Plugin, PluginsOf } from './plugin.cjs';
+import { Phase, PhaseConfig, SchedulePhase } from './phase.cjs';
 import { Archetype, ArchetypeID } from './archetype.cjs';
-import { SystemContext, Query, QueryBuilder, QueryCache, QueryResolver } from './query.cjs';
+import { Query, QueryBuilder } from './query.cjs';
+import { QueryCache, QueryResolver } from './query_cache.cjs';
+import { QueryTerms } from './query_terms.cjs';
+import { SystemContext } from './system_context.cjs';
 import { EntityID } from './entity.cjs';
 import { ComponentCursor, ReadonlyComponentCursor, ReadonlyComponentRef } from './ref.cjs';
 import { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, CompleteFieldValues, Bundle, BundleOrDef, StrictBundles, DefsOf } from './component.cjs';
 import { SparseComponentDef, SparseComponentID } from './sparse_store.cjs';
 import { RelationDef } from './relation.cjs';
 import { SystemFn, SystemConfig, SystemDescriptor, TypedSystemConfig, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.cjs';
+import { SystemEntry, SystemSet, SystemSetConfig } from './system_set.cjs';
 import { BitSet, TypedArrayTag } from '../../type_primitives/index.cjs';
 import { StoreLayoutListener } from './store_layout_listener.cjs';
 import { ComputeBackend } from './compute_backend.cjs';
-import { ResolvedECSMemory, ECSMemoryOptions } from './ecs_memory.cjs';
-export interface ECSOptions {
-    fixedTimestep?: number;
-    maxFixedSteps?: number;
-    /** Sink for dev-mode engine diagnostics (currently the schedule's
-     * dropped-ordering-edge warning). Defaults to `console.warn`. Mirrors the
-     * `FrameTraceSink` seam's injectable style — no global logger. */
-    onWarn?: (message: string) => void;
-    /** How the world's memory is sized and backed — the single
-     * sizing surface, replacing the pre-release `initialCapacity` +
-     * `bufferAllocator` pair. Express intent through exactly one arm:
-     * `{ budget: { entities } }` (derive everything), `{ maxBytes }`
-     * (explicit cap), `{ wasm: { memory } | { maximumPages } }` (the SAB
-     * IS a WebAssembly.Memory — zero-copy with a WASM `ComputeBackend`), or
-     * `{ allocator }` (expert escape hatch, in-place-typed).
-     * Omitted ⇒ growable backing with a 256 MiB cap and 1024-row columns.
-     * The resolved plan is exposed as `ECS.memoryPlan`. */
-    memory?: ECSMemoryOptions;
-    /** Consumer-declared SAB regions, forwarded to `Store`. 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. Replaces the eight game-named region options
-     * (`terrain_map_radius`, `spatial_grid_*`, `army_*`, `flow_field_*`,
-     * `actionRingCapacitySlots`) the ECS used to carry. */
-    regions?: readonly StoreRegionSpec[];
-    /** Byte size of the opt-in sim-bindings region, forwarded to `Store`.
-     * A consumer that attaches a WASM `ComputeBackend` passes its own size — for
-     * this game, `@internal/sim`'s `SIM_BINDINGS_BYTES` (computed from the binding
-     * manifest) — so the host can publish the `(component_id, field_id)` IDs the
-     * accelerated systems read. Omitted / 0 ⇒ no region: a pure-TS world pays
-     * nothing for the WASM seam. The size is a runtime input, not an engine ABI
-     * constant; it is de-welded from the generated ABI. */
-    bindingsRegionBytes?: number;
-    /** Opt into the **determinism surface**, forwarded to
-     * `Store`. Default `false`. When `false`, the canonical-ordering methods
-     * (`stateHash`, `snapshotSparse`, `restoreSparse`) throw
-     * `DETERMINISM_DISABLED`; when `true`, today's replay/hash behavior is
-     * reproduced bit-for-bit. Determinism is the implementer's choice — our
-     * server match opts in (replay verification), the client stays off (it rolls
-     * back via diffs, not re-sim). The flag gates ONLY that surface: memory-safety
-     * invariants (the in-place SAB allocator) and the `enabled_count`
-     * partition are always-on regardless. */
-    deterministic?: boolean;
-}
-export declare class ECS implements QueryResolver {
-    private readonly store;
-    private readonly schedule;
-    private readonly ctx;
-    /** Component observers. Inert until `observe(...)` is
-     * called — the structural-flush fast path is byte-for-byte unchanged. */
-    private readonly _observers;
-    /** Relations: register/add/remove/has, wildcard + traversal reads,
-     * reverse-index compaction. See `ECSRelations`. */
-    readonly relations: ECSRelations;
-    /** Host-side event channels + signals: register/registerSignal/emit/read
-     * (system-side `ctx.emit` is unchanged). See `ECSEvents`. */
-    readonly events: ECSEvents;
-    /** World resources: register/get/set/remove/has. See `ECSResources`. */
+import { ResolvedECSMemory } from './ecs_memory.cjs';
+import { ECSOptions } from './ecs_options.cjs';
+import { computeArchetypeClosure } from './archetype_closure.cjs';
+/** `ECSOptions` moved to `ecs_options.ts` with the guards that read it. The
+ * re-export holds the name a caller already imports from this module. */
+export type { ECSOptions };
+/** The plugins installed on a world. Each optional subsystem contributes
+ * its facade property here, so a world that never installed one cannot name it.
+ * The empty default keeps `ECS` usable unparameterised. */
+export type Plugins = object;
+export declare class ECS<C extends Plugins = object> implements QueryResolver {
+    /** Phantom. Carries the installed-plugin surface so `C` is measurable
+     * to the compiler. Declared, never assigned, and erased from the emitted
+     * JavaScript, so it costs a world nothing. */
+    readonly __plugins?: C;
+    /** Build a world with plugins installed.
+     *
+     * The returned type is the world intersected with the facades its plugins
+     * contribute, so `ECS.create({ plugins: [relations()] }).relations` type-checks
+     * and the same read on a bare `new ECS()` does not. Reach for `new ECS()`
+     * when the world needs none of the optional subsystems: that world does not
+     * carry their code.
+     *
+     * @example
+     * import { relations } from "@oasys/oecs/relations";
+     * const world = ECS.create({ plugins: [relations()] });
+     * world.relations.register();
+     */
+    static create<const P extends readonly Plugin<object>[]>(options?: ECSOptions & {
+        readonly plugins?: P;
+    }): ECS<PluginsOf<P>> & PluginsOf<P>;
+    /** The host a plugin installs through. Built per world, once per
+     * install. Cold path. */
+    private _pluginHost;
+    /** Where this world's bytes are, for a plugin that reads them directly.
+     * Built once, at install.
+     *
+     * `backing` is a getter, because a reader can attach after a grow, and a
+     * grow replaces the buffer the world started with. The wasm memory
+     * survives a grow, so it answers first. Cold path. */
+    private _pluginMemory;
+    private readonly _store;
+    private readonly _schedule;
+    private readonly _ctx;
+    /** What each plugin contributes to the archetype closure `startup()`
+     * plants. Empty on a world that installed no such plugin, and read once, at
+     * startup. */
+    private readonly _prewarmSources;
+    /** What each plugin ends when the world goes away, in install order. */
+    private readonly _disposeHooks;
+    /** The consumers of the tick-tail detection point, in install order. Each
+     * one runs once per `update()` with the change tick of the point. Empty on
+     * a world that installed no consumer, and the tail reads the length once. */
+    private readonly _settleHooks;
+    /** World resources, to register, get, set, remove and test. See
+     * `ECSResources`. */
     readonly resources: ECSResources;
-    /** Determinism surface: capture/restore (full + sparse), stateHash,
-     * the `deterministic` flag. See `ECSSnapshots`. */
+    /** Determinism: `stateHash()` and the `deterministic` flag, both properties
+     * of the world itself. Capture and restore are not here. They arrive with
+     * the snapshot plugin, which replaces this with a widened facade, so a
+     * world that never installs it carries no serialization code. */
     readonly snapshots: ECSSnapshots;
-    private readonly systems;
-    private nextSystemId;
+    private readonly _systems;
+    private _nextSystemId;
     private _tick;
     private _updating;
     private _fixedTimestep;
     private _accumulator;
     private _maxFixedSteps;
-    private readonly scratchMask;
+    private readonly _scratchMask;
     private _nextQueryIdCounter;
-    /** @internal Query-composition caches (QueryResolver seam) — not public API. */
-    readonly _caches: QueryCache;
+    /** @internal Query-composition caches (QueryResolver seam), not public API. */
+    readonly caches: QueryCache;
     private readonly _layoutSubscribers;
     private _backend;
+    private _routePlanner;
     private readonly _memory;
     /** What `ECSOptions.memory` resolved to: backing allocator kind,
      * column capacity, entity-index reservation, byte cap, and a
-     * human-readable derivation trace. Diagnostics surface — log it when
+     * human-readable derivation trace. Diagnostics surface, log it when
      * sizing questions come up instead of reverse-engineering the SAB. */
     get memoryPlan(): ResolvedECSMemory;
     /** The backing `WebAssembly.Memory` when `memory.wasm` was used (both
      * bring-your-own and engine-constructed), else `null`. A consumer hands
-     * this to its WASM `ComputeBackend` so the sim and the live columns
+     * this to its WASM `ComputeBackend` so the module and the live columns
      * share the same bytes. */
     get wasmMemory(): WebAssembly.Memory | null;
     constructor(options?: ECSOptions);
     /** Batch variant of `regionHandle` for hosts wiring several consumer
-     * regions at startup: returns the handles in argument order, never null —
-     * throws ONE `REGION_NOT_DECLARED` naming every missing region id instead
+     * regions at startup: returns the handles in argument order, never null,
+     * throws one `REGION_NOT_DECLARED` naming every missing region id instead
      * of a null-guard per region. Same staleness rule as `regionHandle`:
      * re-fetch after a SAB grow. */
     regionHandles(...regionIds: number[]): ColumnStoreRegionHandle[];
-    /** Subscribe to SAB-layout publications. `listener.setLayout(0)` is
-     * called immediately to seed the initial layout, then again after
-     * every SAB grow / extend (the `view_stamp` republish protocol).
-     * Returns an unsubscribe function.
+    /** Subscribe to store-layout publications. `listener.setLayout(storeBase)`
+     * is called immediately to seed the initial layout, then again after every
+     * grow and extend (the `view_stamp` republish protocol). The argument is the
+     * byte offset of the header inside the backing, and every offset the
+     * listener then reads from the bytes is relative to it. Returns an
+     * unsubscribe function.
      *
-     * The engine has no concept of what subscribes — it publishes SAB layouts
+     * The engine has no concept of what subscribes. It publishes SAB layouts
      * and walks away. A consumer subscribes whatever wrapper it owns (a compute
      * backend, a Worker proxy, a debug recorder) and drives it from its own
      * code. A `ComputeBackend` is subscribed automatically by `attachBackend`,
      * so most consumers call that rather than this directly. */
-    onStoreLayoutPublished(listener: StoreLayoutListener): () => void;
+    subscribeLayout(listener: StoreLayoutListener): () => void;
     /** Attach an opt-in compute backend. Default is none: a bare `ECS`
      * runs pure-TS systems and the schedule's dispatch is byte-for-byte the
      * no-backend path. Once attached, a scheduled system carrying a
      * `backendHandle` (its `SystemConfig`) is executed via `backend.run(handle)`
-     * instead of its `fn` closure; systems without a handle are unaffected.
+     * instead of its `fn` closure. Systems without a handle are unaffected.
      *
      * The backend is also subscribed as a SAB-layout listener (seeded now, then
-     * republished on every grow), folding in the `onStoreLayoutPublished` seam.
+     * republished on every grow), folding in the `subscribeLayout` seam.
      * Returns a detach function that unsubscribes the layout listener and reverts
      * the schedule to the pure-TS path.
      *
      * One backend per ECS: attaching while one is already attached throws in
      * `DEV` (detach first). The engine never inspects the backend beyond
-     * `setLayout` / `run` — it carries no game vocabulary. */
+     * `setLayout` and `run`. It carries no game vocabulary. */
     attachBackend(backend: ComputeBackend): () => void;
     get fixedTimestep(): number;
     set fixedTimestep(value: number);
@@ -144,19 +149,19 @@ export declare class ECS implements QueryResolver {
      * flush, command, observer firing, and event during `update()`, so a consumer
      * can reconstruct exactly what travelled through the ECS each frame. The sink
      * also receives a `phaseBoundary(phase)` at each phase's post-flush settle
-     * point — the safe seam to read `stateHash()` between phases of one frame and
+     * point, the safe seam to read `stateHash()` between phases of one frame and
      * bisect a divergence to the exact phase. The seam is
-     * `DEV`-gated end to end — in a production build this setter keeps an empty
-     * body and the world never retains a sink. The sink only observes; it does not
+     * `DEV`-gated end to end, in a production build this setter keeps an empty
+     * body and the world never retains a sink. The sink only observes. It does not
      * perturb `stateHash`, ordering, or any behaviour. */
     setTrace(sink: FrameTraceSink | null): void;
     /**
      * Register a dense component and get back its typed handle. Record syntax
-     * gives per-field type control; the array shorthand types every field the
-     * same (default `"f64"` — rejected on a `{ deterministic: true }` world,
+     * gives per-field type control. The array shorthand types every field the
+     * same (default `"f64"`, rejected on a `{ deterministic: true }` world,
      * pass an explicit integer type there). An empty schema `{}` is a
      * tag. `opts.name` labels dev-mode diagnostics (`'Pos' (component 5)`
-     * instead of `component 5`) — diagnostic only, no behavioural effect.
+     * instead of `component 5`), diagnostic only, no behavioural effect.
      *
      * The handle is *callable*: `Pos({ x: 1 })` mints a `Bundle` for the
      * attach surfaces (`spawnBundle`, `ctx.commands.spawn`, `addComponent`).
@@ -165,7 +170,7 @@ export declare class ECS implements QueryResolver {
      * const Pos = ecs.registerComponent({ x: "f64", y: "f64" });
      * const Hp = ecs.registerComponent(["current", "max"], "i32");
      * const Frozen = ecs.registerComponent({}, { name: "Frozen" }); // tag
-     * ecs.getField(e, Pos, "x"); // field names/types flow from the schema
+     * ecs.getField(e, Pos, "x"); // field names and types flow from the schema
      */
     registerComponent<S extends Record<string, TypedArrayTag>>(schema: S, opts?: ComponentRegisterOptions): ComponentDef<S>;
     registerComponent<const F extends readonly string[], T extends TypedArrayTag = "f64">(fields: F, type?: T, opts?: ComponentRegisterOptions): ComponentDef<{
@@ -176,35 +181,42 @@ export declare class ECS implements QueryResolver {
         readonly [K in F[number]]: T;
     }>;
     /**
-     * Spawn an entity, immediately. Bare `spawn()` creates an empty entity —
+     * Spawn an entity, immediately. Bare `spawn()` creates an empty entity,
      * attach components afterward. `spawn(template, overrides?)` lands
      * directly in the template's archetype with zero archetype transitions,
      * applying optional flat per-field overrides on top of the template
      * defaults. Inside a system use `ctx.commands.spawn(...)` instead.
      *
+     * `spawn` takes a template. It does not take a component definition, and it
+     * does not take a bundle. For components with no template, use `spawnBundle`.
+     *
      * @example
      * const e = ecs.spawn();
      * ecs.addComponent(e, Pos, { x: 0, y: 0 });
      *
-     * const Bullet = ecs.template([{ def: Pos, values: { x: 0, y: 0 } }]);
+     * // Build a template from callable bundles.
+     * const Bullet = ecs.template(Pos({ x: 0, y: 0 }), Vel({ vx: 1, vy: 0 }));
      * const b = ecs.spawn(Bullet, { x: 5 }); // override a template default
+     *
+     * // One entity, components given directly, no template.
+     * const c = ecs.spawnBundle(Pos({ x: 0, y: 0 }), Vel({ vx: 1, vy: 0 }));
      */
     spawn(): EntityID;
     spawn<Defs extends readonly ComponentDef[]>(template: Template<Defs>, overrides?: TemplateOverrides<Defs>): EntityID;
     /**
-     * Spawn an entity from varargs bundles (§bundles) — the immediate
+     * Spawn an entity from varargs bundles, the immediate
      * host-side analog of `ctx.commands.spawn`, and the same callable-bundle
-     * grammar as `addComponents` / `template`. `ecs.spawnBundle(Pos({x,y}),
-     * Vel({vx:1}), IsEnemy)` collapses the attach shapes into one; each item is
+     * grammar as `addComponents` and `template`. `ecs.spawnBundle(Pos({x,y}),
+     * Vel({vx:1}), IsEnemy)` collapses the attach shapes into one. Each item is
      * checked against its own def's schema (`StrictBundles`). Bundles are applied
-     * immediately; a single combined-archetype insertion (one transition instead
-     * of one-per-component) is a later optimization — for now this mirrors the
+     * immediately. A single combined-archetype insertion (one transition instead
+     * of one-per-component) is a later optimization, for now this mirrors the
      * per-component `addComponent` path (unlike `addComponents`, which batches).
      *
-     * Immediate — inside a system use the deferred `ctx.commands.spawn(...)`
+     * Immediate, inside a system use the deferred `ctx.commands.spawn(...)`
      * (calling this from a system body throws in DEV). Note the redirect trades
      * timing: `commands.spawn` returns the id now but defers the attaches to the
-     * phase flush, so the entity sits in its empty/partial archetype until then —
+     * phase flush, so the entity sits in its empty and partial archetype until then,
      * unlike `spawnBundle`'s immediate, fully-populated archetype.
      */
     spawnBundle<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): EntityID;
@@ -212,32 +224,34 @@ export declare class ECS implements QueryResolver {
      * shared `overrides` object to every spawned row (same typed keys as
      * `spawn`). Field writes are O(columns) (one `TypedArray.fill` per
      * column), not O(count×columns). Returns the new ids in spawn order.
-     * Immediate — inside a system use `ctx.commands.spawn` per entity (calling
+     * Immediate, inside a system use `ctx.commands.spawn` per entity (calling
      * this from a system body throws in DEV). */
     spawnMany<Defs extends readonly ComponentDef[]>(template: Template<Defs>, count: number, overrides?: TemplateOverrides<Defs>): EntityID[];
     /** DEV-only: throw when an *immediate* host structural mutator is called
-     * from inside one of THIS world's system bodies (or an observer / onAdded
-     * hook — they run in the same access spans). One rule for every host
-     * structural mutator — despawn, add/remove(Components), batchAdd/Remove,
-     * disable/enable, AND the spawn family (spawn/spawnBundle/spawnMany): an
-     * immediate structural op mid-schedule can move or swap rows a running query
-     * is walking — or, for a spawn-append into that archetype, trip a column
-     * realloc under it — and it is invisible to observers. The archetype-level
+     * from inside one of this world's system bodies. An observer callback and an
+     * `onAdded` hook run in the same access span, so the guard covers them too.
+     * One rule covers every host structural mutator: `despawn`, `addComponent`,
+     * `addComponents`, `removeComponent`, `removeComponents`,
+     * `batchAddComponent`, `batchRemoveComponent`, `disable`, `enable`, and the
+     * spawn family (`spawn`, `spawnBundle` and `spawnMany`).
+     * An immediate structural op mid-schedule can move or swap rows
+     * a running query is walking. A spawn-append into that archetype can trip a
+     * column realloc under it. Neither is visible to observers. The archetype-level
      * `_iterDepth` guard only catches mutations touching the archetype currently
      * being iterated (and the append paths skip even that), so an op landing
-     * elsewhere would silently skip observers; the receiver rule ("inside a
+     * elsewhere would silently skip observers. The receiver rule ("inside a
      * system, use ctx.commands") is enforced wholesale here.
      *
-     * `_updating` scopes the guard to THIS world: the accessCheck slot is
+     * `_updating` scopes the guard to this world: the accessCheck slot is
      * process-global, so without it a system of world A mutating world B (a
-     * supported pattern — B is not mid-iteration) would false-throw. */
-    private _assertHostMutationOutsideSystem;
-    /** Immediately destroy an entity — `ecs.despawn(e); ecs.isAlive(e)` is
+     * supported pattern. B is not mid-iteration) would false-throw. */
+    private _assertOutsideSystem;
+    /** Immediately destroy an entity, `ecs.despawn(e); ecs.isAlive(e)` is
      *  `false` on the next line, matching the immediacy of every other host
      *  facade mutation. Inside a system the buffered path is
-     *  `ctx.commands.despawn` (applied at the phase flush); calling this from
-     *  a system body throws in DEV, since an immediate destroy mid-iteration
-     *  can invalidate rows the running query is walking. */
+     *  `ctx.commands.despawn`, applied at the phase flush. A call from a system
+     *  body throws in DEV, because an immediate destroy mid-iteration can
+     *  invalidate rows the running query is walking. */
     despawn(entityId: EntityID): this;
     /** Disable `entityId` (idempotent). Excluded from default queries until re-enabled. */
     disable(entityId: EntityID): this;
@@ -245,61 +259,61 @@ export declare class ECS implements QueryResolver {
     enable(entityId: EntityID): this;
     /**
      * Attach a component to an entity, immediately (inside a system, use the
-     * deferred `ctx.commands.add`). Three shapes: a bare def attaches a tag; a
-     * bundle (`Pos({ x: 1 })`) zero-fills omitted fields; the explicit
+     * deferred `ctx.commands.add`). Three shapes: a bare def attaches a tag. A
+     * bundle (`Pos({ x: 1 })`) zero-fills omitted fields. The explicit
      * `(e, def, values)` form demands every field, so a typo'd or missing
      * field is a compile error.
      *
      * @example
      * ecs.addComponent(e, Frozen);                 // tag
-     * ecs.addComponent(e, Pos({ x: 1 }));          // bundle — y zero-fills
+     * ecs.addComponent(e, Pos({ x: 1 }));          // bundle, y zero-fills
      * ecs.addComponent(e, Pos, { x: 1, y: 2 });    // complete values
      */
     addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): this;
     addComponent<S extends ComponentSchema>(entityId: EntityID, bundle: Bundle<S>): this;
     addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
     /** Batch-attach several components in one archetype transition. Takes the
-     * same callable-bundle varargs as `spawnBundle` — `world.addComponents(e,
-     * Pos({ x, y }), Vel({ vx }), Frozen)` — each item checked against its own
-     * def's schema (a misspelled or cross-component field is a compile error;
-     * tags refuse values). Omitted fields zero-fill. */
+     * same callable-bundle varargs as `spawnBundle`, `world.addComponents(e,
+     * Pos({ x, y }), Vel({ vx }), Frozen)`, each item checked against its own
+     * def's schema (a misspelled or cross-component field is a compile error,
+     * and a tag refuses values). Omitted fields zero-fill. */
     addComponents<Items extends readonly BundleOrDef[]>(entityId: EntityID, ...items: StrictBundles<Items>): this;
     removeComponent(entityId: EntityID, def: ComponentDef): this;
-    /** Detach several components in one archetype transition — the varargs
-     * mirror of `addComponents` (bare defs; removing needs no values). */
+    /** Detach several components in one archetype transition, the varargs
+     * mirror of `addComponents` (bare defs, removing needs no values). */
     removeComponents(entityId: EntityID, ...defs: ComponentDef[]): this;
     /**
-     * Bulk add a component to ALL entities in the given archetype.
+     * Bulk add a component to all entities in the given archetype.
      * O(columns) via TypedArray.set() instead of O(N×columns).
      *
      * Takes an `ArchetypeID` (from `ArchetypeView.id`) rather than a concrete
-     * `Archetype` — the concrete type is internal.
+     * `Archetype`, the concrete type is internal.
      */
     batchAddComponent(src: ArchetypeID, def: ComponentDef<Record<string, never>>): this;
     batchAddComponent<S extends ComponentSchema>(src: ArchetypeID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
     /**
-     * Bulk remove a component from ALL entities in the given archetype.
+     * Bulk remove a component from all entities in the given archetype.
      * O(columns) via TypedArray.set() instead of O(N×columns).
      *
-     * Takes an `ArchetypeID` (from `ArchetypeView.id`); see `batchAddComponent`.
+     * Takes an `ArchetypeID`, from `ArchetypeView.id`. See `batchAddComponent`.
      */
     batchRemoveComponent(src: ArchetypeID, def: ComponentDef): this;
     getField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S): number;
     /** Host-side parity with `SystemContext.refRead`: a
-     * read-only whole-component view for tooling/tests, instead of reading
-     * field-by-field. Same advisory-`readonly` semantics as the ctx variant;
-     * no `_changedTick` bump. Dev-throws on a dead entity, or when the entity
-     * doesn't hold the component (tags included — no fields, nothing to ref).
+     * read-only whole-component view for tooling and tests, instead of reading
+     * field-by-field. Same advisory-`readonly` semantics as the ctx variant,
+     * and no `_changedTick` bump. Dev-throws on a dead entity, or when the entity
+     * doesn't hold the component (tags included, no fields, nothing to ref).
      *
      * **Staleness:** unlike ctx refs (protected by deferred structural changes
-     * until the phase flush), host-side structural mutations apply immediately —
-     * any `addComponent`/`removeComponent`/`despawn` after creating the ref can
+     * until the phase flush), host-side structural mutations apply immediately,
+     * any `addComponent`, `removeComponent` and `despawn` after creating the ref can
      * row-swap so the old ref silently reads *another entity's* data. The ref is
-     * only valid until the next structural mutation; treat it as an immediate
+     * only valid until the next structural mutation. Treat it as an immediate
      * single-expression read and re-create it after any structural change. */
     refRead<S extends ComponentSchema>(def: ComponentDef<S>, entityId: EntityID): ReadonlyComponentRef<S>;
     /**
-     * A re-pointable single-entity cursor over `def` — the by-id sweep accessor.
+     * A re-pointable single-entity cursor over `def`, the by-id sweep accessor.
      *
      * `refRead` resolves an entity one time, and each field after that is almost
      * free. But it allocates one accessor for each entity. That allocation is the
@@ -308,33 +322,62 @@ export declare class ECS implements QueryResolver {
      * that exists. In a loop over a list of entities, the allocation is not
      * necessary: the code discards each accessor, and it then makes an equal
      * accessor for the next entity. You make a cursor one time, and you then
-     * point it again:
+     * move it again:
      *
      *   const p = ecs.cursor(Pos);
      *   for (let i = 0; i < ids.length; i++) {
      *     p.at(ids[i]);
-     *     p.x += p.y;
+     *     p.x += p.y
      *   }
      *
-     * Reach for it when you touch **many entities** by id; reach for `refRead` /
-     * `ref` for a single entity, and for `eachChunk` whenever a query can express
+     * Reach for it when you touch many entities by id. Reach for `refRead` or
+     * `ref` for a single entity, and for `forEachChunk` whenever a query can express
      * the set. A column walk resolves nothing for each row, so it stays quicker
-     * than a cursor — a cursor removes the allocation, not the resolution.
+     * than a cursor, a cursor removes the allocation, not the resolution.
      *
-     * Mutable — every `at()` stamps the component's change tick, like `ctx.ref`.
+     * Mutable, every `at()` stamps the component's change tick, like `ctx.ref`.
      * See `cursorRead` for the read-only variant.
      *
      * **Staleness:** safer than a held ref, because `at()` re-resolves the
-     * archetype and row each time — a structural mutation between two `at()` calls
+     * archetype and row each time, a structural mutation between two `at()` calls
      * cannot make it read the wrong entity. Only the window between one `at()` and
      * the field accesses following it must be free of structural mutation.
      */
     cursor<S extends ComponentSchema>(def: ComponentDef<S>): ComponentCursor<S>;
-    /** Read-only {@link cursor}: no change-tick stamp on `at()`. Advisory only —
+    /** Read-only {@link cursor}: no change-tick stamp on `at()`. Advisory only,
      * same caveat as `refRead` (the setters exist on the shared prototype). */
     cursorRead<S extends ComponentSchema>(def: ComponentDef<S>): ReadonlyComponentCursor<S>;
+    /**
+     * A re-pointable single-entity cursor over a sparse component, the sparse
+     * sibling of {@link cursor}, and the fastest read by id the engine has.
+     *
+     * A sparse component's columns are indexed by entity index, so `at(entity)`
+     * writes one field and a field access is one load: there is no archetype
+     * and no row to resolve, which is what a dense cursor must do on every
+     * `at()`. Make the cursor one time and move it in the loop:
+     *
+     *   const hp = ecs.sparseCursor(Health);
+     *   for (let i = 0; i < ids.length; i++) {
+     *     hp.at(ids[i]);
+     *     hp.current -= damage[i];
+     *   }
+     *
+     * Mutable, like `cursor`. Once the component keeps row ticks
+     * (`trackRows`, or an entity-level `onSet`), `at()` records the entity for
+     * them, as the dense cursor does. See `sparseCursorRead` for the read-only
+     * variant.
+     *
+     * **Membership:** in development `at()` throws when the entity is dead or
+     * does not hold the component. In production it does not test, and a read
+     * then gives whatever the column holds at that index. Test with `hasSparse`
+     * first when the component can be absent.
+     */
+    sparseCursor<S extends ComponentSchema>(def: SparseComponentDef<S>): ComponentCursor<S>;
+    /** Read-only {@link sparseCursor}. Advisory only, same caveat as
+     * `cursorRead` (the setters exist on the shared prototype). */
+    sparseCursorRead<S extends ComponentSchema>(def: SparseComponentDef<S>): ReadonlyComponentCursor<S>;
     /** Total sibling of {@link getField}: `undefined` when the
-     * entity is dead or doesn't hold the component, instead of a dev throw /
+     * entity is dead or doesn't hold the component, instead of a dev throw and a
      * prod garbage read. The safe way to probe-and-read in one call:
      * `ecs.tryGetField(e, Health, "current") ?? 0`. */
     tryGetField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S): number | undefined;
@@ -346,72 +389,72 @@ export declare class ECS implements QueryResolver {
     updateField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, fn: (current: number) => number): number;
     /**
      * Get the live, cached query matching entities that have **all** of
-     * `defs`. Queries are deduplicated by mask — calling this twice with the
-     * same terms returns the same instance — so build once at setup and reuse;
-     * the view stays live as archetypes appear. Refine with `.and()` /
-     * `.without()` / `.anyOf()`; iterate with `eachChunk` (mutating hot path),
+     * `defs`. Queries are deduplicated by mask, calling this twice with the
+     * same terms returns the same instance, so build once at setup and reuse.
+     * The view stays live as archetypes appear. Refine with `.and()`,
+     * `.not()` or `.or()`. Iterate with `forEachChunk` (mutating hot path),
      * `forEach` (per-archetype), or `forEachEntity` (per-entity).
      *
      * @example
      * const movers = ecs.query(Pos, Vel);
-     * movers.eachChunk((cols, count) => {
+     * movers.forEachChunk((cols, count) => {
      *   const { x, y } = cols.mut(Pos);
      *   const { vx, vy } = cols.read(Vel);
      *   for (let i = 0; i < count; i++) { x[i] += vx[i]; y[i] += vy[i]; }
      * });
      */
     query<T extends ComponentDef[]>(...defs: T): Query<T>;
-    _nextQueryId(): number;
-    /** QueryResolver implementation — creates or retrieves a cached Query.
+    nextQueryId(): number;
+    /** QueryResolver implementation, creates or retrieves a cached Query.
      *
      * **Mask ownership: borrowed.** The three mask arguments are read, never
-     * retained — the mint path copies each one into the `Query`, into the dedup
+     * retained, the mint path copies each one into the `Query`, into the dedup
      * entry, and (via `Store.registerQuery`) into the registered-query record.
      * So callers may pass a scratch mask they intend to reuse (`ecs.query`) or
-     * a live mask they still own (`Query.and` / `.without` / `.anyOf` pass
-     * `this._include` etc.). Do NOT add a caller-side `.copy()` "for safety":
+     * a live mask they still own (`Query.and`, `.not` and `.or` pass
+     * `this._include` etc.). Do not add a caller-side `.copy()` "for safety":
      * on the cache-hit path that is a per-call BitSet + `number[]` allocation
      * for nothing. */
-    _resolveQuery(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, defs: readonly ComponentDef[]): Query<any>;
+    resolveQuery(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, defs: readonly ComponentDef[]): Query<any>;
     /**
      * Register a system and get its scheduling handle. The config form is the
-     * production shape: it declares the access surface (`reads` / `writes` are
-     * mandatory; `spawns` / `despawns` / resource and sparse/relation terms
-     * optional), which is enforced at runtime in dev *and* narrows `ctx` at
+     * production shape. It declares the access surface. `reads` and `writes` are
+     * mandatory. The `spawns`, `despawns`, resource, sparse and relation terms
+     * are optional. The runtime enforces the surface in dev, and it narrows `ctx` at
      * the type level so undeclared access fails to compile. Registration does
-     * not schedule — pass the returned descriptor to
+     * not schedule, pass the returned descriptor to
      * `ecs.addSystems(SCHEDULE.UPDATE, ...)`.
      *
      * @example
-     * // Full config — declared access, dev-checked and compile-checked
+     * // Full config, declared access, dev-checked and compile-checked
      * const move = ecs.registerSystem({
      *   reads: [Vel],
      *   writes: [Pos],
      *   fn(ctx, dt) {
-     *     movers.eachChunk((cols, count) => { ... });
+     *     movers.forEachChunk((cols, count) => { ... });
      *   },
      * });
      * ecs.addSystems(SCHEDULE.UPDATE, move);
      *
      * @example
-     * // Bare function (no declared access — any component touch throws in dev)
+     * // Bare function (no declared access, any component touch throws in dev)
      * ecs.registerSystem((ctx, dt) => { ... });
      * // Function + query builder (query resolved at registration time)
-     * ecs.registerSystem((q, ctx, dt) => { q.forEach((arch) => { ... }); }, (qb) => qb.with(Pos, Vel));
+     * ecs.registerSystem((q, ctx, dt) => { q.forEach((arch) => { ... }); }, (qb) => qb.and(Pos, Vel));
      */
     registerSystem(fn: SystemFn): SystemDescriptor;
     registerSystem<Defs extends readonly ComponentDef[]>(fn: (q: Query<Defs>, ctx: SystemContext, dt: number) => void, queryFn: (qb: QueryBuilder) => Query<Defs>): SystemDescriptor;
-    /** `exclusive: true` grants full world access at runtime (§system.ts), so
-     * the context stays fully permissive at the type layer too. Declared BEFORE
+    /** `exclusive: true` grants full world access at runtime (system.ts), so
+     * the context stays fully permissive at the type layer too. Declared before
      * the typed-config overload so exclusive configs never get narrowed. */
     registerSystem(config: SystemConfig & {
         readonly exclusive: true;
     }): SystemDescriptor;
-    /** Config form (§typestate, system.ts): the declaration lists are inferred
-     * as literal tuples and `fn` / `onAdded` receive
-     * `SystemContext<DeclaredAccess<…>>` — undeclared access fails to compile
+    /** Config form (system.ts): the declaration lists are inferred
+     * as literal tuples, and `fn` and `onAdded` receive
+     * `SystemContext<DeclaredAccess<…>>`, undeclared access fails to compile
      * with the same taxonomy the runtime `accessCheck` throws with in
-     * `DEV`. A config VALUE typed as plain `SystemConfig` (dynamically
+     * `DEV`. A config value typed as plain `SystemConfig` (dynamically
      * built) still matches: its erased declaration lists compute a permissive
      * access record. Escape hatch: annotate `fn(ctx: SystemContext, dt)`
      * explicitly to keep a system permissive at compile time. */
@@ -420,10 +463,10 @@ export declare class ECS implements QueryResolver {
     get systemCount(): number;
     /**
      * Run the startup phases, once, before the first `update()`. Prewarms
-     * every archetype the registered systems/observers can produce, runs each
+     * every archetype the registered systems and observers can produce, runs each
      * system's `onAdded` hook, then the `PRE_STARTUP` → `STARTUP` →
      * `POST_STARTUP` schedule. Events emitted during startup are drained at
-     * its tail — they do not leak into frame 1.
+     * its tail. They do not leak into frame 1.
      *
      * @example
      * ecs.addSystems(SCHEDULE.UPDATE, move);
@@ -431,15 +474,15 @@ export declare class ECS implements QueryResolver {
      * ecs.update(1 / 60); // now tick every frame
      */
     startup(): void;
-    /** Compute the archetype closure from every registered system's AND
+    /** Compute the archetype closure from every registered system's and
      * observer's `spawns` + `transitions` and ask the store to plant the
      * whole set in one `extendColumnStore` call. Observers carry the same
      * access shape systems do (a synthesized `SystemDescriptor`), so an
-     * observer that spawns/transitions gets its target archetype prewarmed
+     * observer that spawns and transitions gets its target archetype prewarmed
      * too rather than first-touching lazily mid-tick. Exposed as
-     * `private` because the only caller is `startup()`; visible to tests via
-     * the `archetype_count` delta on the public ECS facade. */
-    private prewarmArchetypes;
+     * `private` because the only caller is `startup()`. Visible to tests via
+     * the `archetypeCount` delta on the public ECS facade. */
+    private _prewarmArchetypes;
     /**
      * Advance the world one frame. Runs the fixed-timestep accumulator loop
      * (`FIXED_UPDATE`, when any fixed system is registered), then
@@ -459,24 +502,24 @@ export declare class ECS implements QueryResolver {
     update(dt: number): void;
     dispose(): void;
     /** Register an archetype template. Resolves the component set +
-     * default field values to a target archetype once (creating it if absent —
-     * fits the prewarm model), so later `spawn` / `spawnMany` calls land
-     * entities directly in that archetype with **zero archetype transitions**.
+     * default field values to a target archetype once (creating it if absent,
+     * fits the prewarm model), so a later `spawn` or `spawnMany` call lands
+     * entities directly in that archetype with no archetype transition.
      *
      *   const Bullet = ecs.template(Position({ x: 0, y: 0 }), Velocity({ vx: 0, vy: 0 }));
      *
-     * Takes the same callable-bundle varargs as `spawnBundle` / `addComponents`
-     * (each item schema-checked against its own def); the resulting
+     * Takes the same callable-bundle varargs as `spawnBundle` and
+     * `addComponents`, each item schema-checked against its own def. The resulting
      * `Template<[Position, Velocity]>` keeps the typed key set that `spawn`'s
-     * `overrides` map over. Not a pass-through — it normalizes bundles to the
+     * `overrides` map over. Not a pass-through. It normalizes bundles to the
      * store's entry shape, so it lives here with the other real logic, not in the
-     * delegation band. The big win is multi-component entities and bulk spawns; a
+     * delegation band. The big win is multi-component entities and bulk spawns. A
      * single-component spawn is no faster than `spawn` + `addComponent`, which
      * already bump-allocates a fresh entity into the target archetype. */
     template<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): Template<DefsOf<Items>>;
     /** Resolve a consumer-declared SAB region's byte offset by `region_id`, or
      * 0 when absent. Generic, de-gamed replacement for the removed
-     * game-named accessors; pair with the consumer's own region module to
+     * game-named accessors. Pair with the consumer's own region module to
      * materialise a typed view. Delegates to `Store.regionOffset`. */
     regionOffset(regionId: number): number;
     /** A handle (`{ buffer, view, offset, bytes }`) to a consumer-declared SAB
@@ -487,8 +530,8 @@ export declare class ECS implements QueryResolver {
     /** Look up the field index a component reserves for `fieldName`. The
      * index is assigned by `registerComponent` in insertion order and is
      * stable for the lifetime of the ECS. Used by systems that need to
-     * pass `(component_id, field_id)` pairs across the WASM FFI — the Zig
-     * side identifies columns by these numeric IDs. */
+     * pass `(component_id, field_id)` pairs across the WASM FFI, because the
+     * module identifies columns by these numeric ids. */
     fieldId<S extends Record<string, TypedArrayTag>>(def: ComponentDef<S>, fieldName: Extract<keyof S, string>): number;
     /** Resolve an archetype's row index to the `EntityID` at that slot.
      * A WASM system that drains events from the event ring as
@@ -497,24 +540,24 @@ export declare class ECS implements QueryResolver {
      * Throws if the (archId, row) pair is out of range. */
     entityIdAtRow(archetypeId: number, row: number): EntityID;
     /** The single SAB backing every archetype's column views. Exposed for
-     * snapshot/restore, `columnStoreStateHash`-based determinism checks, and
-     * WASM/worker hand-off paths. Mutation flows through the
-     * usual `addComponent` / `removeComponent` / `flush` APIs; readers
+     * snapshot and restore, `columnStoreStateHash`-based determinism checks, and
+     * WASM or worker hand-off paths. Mutation flows through the
+     * usual `addComponent`, `removeComponent` and `flush` APIs. Readers
      * that hold a column view across a grow must consult
      * `header.view_stamp` to detect a republish. */
     get columnStore(): ColumnStore;
     /** Count of live archetypes (including the empty one). Surfaces the
      * Store-side `archetype_count` so tests can assert the
-     * pre-warmed closure was materialised; equally useful for diagnostics. */
+     * pre-warmed closure was materialised. Equally useful for diagnostics. */
     get archetypeCount(): number;
     registerTag(): ComponentDef<Record<string, never>>;
-    /** Register a sparse tag (empty schema) — membership only, no data. */
+    /** Register a sparse tag (empty schema), membership only, no data. */
     registerSparseTag(): SparseComponentDef<Record<string, never>>;
     isAlive(entityId: EntityID): boolean;
     get entityCount(): number;
     hasComponent(entityId: EntityID, def: ComponentDef): boolean;
-    /** Whether `entityId` is currently disabled. Toggle via `disable` / `enable`
-     * (immediate, above the band — they carry the in-system dev guard). */
+    /** Whether `entityId` is currently disabled. Toggle with `disable` or `enable`
+     * (immediate, above the band. They carry the in-system dev guard). */
     isDisabled(entityId: EntityID): boolean;
     addSparse(entityId: EntityID, def: SparseComponentDef<Record<string, never>>): this;
     addSparse<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, values: CompleteFieldValues<S>): this;
@@ -522,65 +565,62 @@ export declare class ECS implements QueryResolver {
     hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
     getSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S): number;
     setSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S, value: number): void;
-    _getLastRunTick(): number;
-    /** Current ECS write tick — the tick `eachChunk` stamps via `cols.mut` (§eachChunk). */
-    _getCurrentTick(): number;
-    _getQueryDirtyEpoch(): number;
-    /** QueryResolver implementation — sparse-membership match path. */
-    _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;
-    /** QueryResolver implementation — backing sparse id of a relation, for the
-     * `(R, *)` wildcard term (`Query.withRelation`). */
-    _relationBackingSparseId(def: RelationDef): SparseComponentID;
-    /** QueryResolver implementation — `(*, T)` wildcard match path. */
-    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
-    /** QueryResolver implementation — depth-ordered hierarchy match path. */
-    _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;
-    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): this;
+    getLastRunTick(): number;
+    /** The change tick, the stamp `forEachChunk` makes via `cols.mut`. */
+    getChangeTick(): number;
+    /** QueryResolver implementation: a chunk loop took `cols.ticks(def)`. */
+    noteScan(cid: number): void;
+    getQueryDirtyEpoch(): number;
+    /** QueryResolver implementation, sparse-membership match path. */
+    forEachSparseMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], cb: (entityId: EntityID) => void): void;
+    /** QueryResolver implementation, backing sparse id of a relation, for the
+     * `(R, *)` wildcard term (`Query.andRelation`). */
+    relationBackingSparseId(def: RelationDef, api: string): SparseComponentID;
+    /** QueryResolver implementation, `(*, T)` wildcard match path. */
+    forEachTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, cb: (entityId: EntityID) => void): void;
+    /** QueryResolver implementation, depth-ordered hierarchy match path. */
+    forEachHierarchyMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, cb: (entityId: EntityID) => void): void;
+    addSystems(phase: SchedulePhase, ...entries: (SystemDescriptor | SystemEntry)[]): this;
+    /**
+     * Add one phase to a loop, and hand back its handle. Setup only, cold path.
+     *
+     * A plugin that owns a slot no longer contends for insertion order inside a
+     * phase the application also writes to. `before` and `after` order the new
+     * phase against the other phases of the same loop, built-in or added.
+     *
+     * The handle belongs to this world, and identity and not name decides which
+     * phase it is, the rule `systemSet` follows.
+     *
+     * @example
+     * const physics = ecs.addPhase("physics", {
+     *   loop: "update",
+     *   after: [SCHEDULE.PRE_UPDATE],
+     *   before: [SCHEDULE.UPDATE]
+     * });
+     * ecs.addSystems(physics, integrate);
+     */
+    addPhase(name: string, config: PhaseConfig): Phase;
     /**
-     * Configure a `SystemSet` — the shared run condition and/or ordering
+     * Configure a `SystemSet`, the shared run condition, or its ordering,
      * every member inherits. Additive and order-independent with respect to
      * `addSystems`: see `Schedule.configureSet`. Returns `this` to chain.
      */
     configureSet(set: SystemSet, config: SystemSetConfig): this;
     /**
-     * Register a per-component observer. Reactions that were
-     * hand-polled every tick — "on `Death` added → spawn corpse", "on `HexPos`
-     * set → mark the spatial index" — become declarative.
-     *
-     * - **`onAdd` / `onRemove`** `(eid, ctx)` fire at the structural-flush
-     *   boundary, after the batch commits, in canonical order (access-topological
-     *   across observers, entity-id order within), looping to a fixed point so
-     *   cascades settle. Determinism: a `stateHash` replay reproduces regardless
-     *   of the order ops were queued.
-     * - **`onDisable` / `onEnable`** `(eid, ctx)` fire at the same flush boundary
-     *   when an entity carrying the component is *disabled* / *enabled*, once
-     *   per net transition, for every component the entity carries
-     *   (a disable is a soft remove of the whole mask from default queries). Like
-     *   `onAdd`/`onRemove`, an *immediate* `ecs.disable()` does not fire — only
-     *   the deferred `ctx.commands.disable()` toggle does. `yieldExisting` seeds enabled
-     *   members only, so a disabled entity is correctly absent at seed.
-     * - **`onSet`** fires at the post-update detection point. Default
-     *   `granularity: "archetype"` fires `(arch, ctx)` once per changed
-     *   archetype-column (the consumer iterates `arch.entityCount` rows) — free,
-     *   reusing the change tick. `granularity: "entity"` fires `(eid, ctx)` once
-     *   per changed entity, draining the opt-in per-row dirty list (registering it
-     *   enables dirty tracking for the component; the producer records via
-     *   `ctx.setField` automatically, or `ctx.markChanged` in a `getColumn`
-     *   hot loop).
-     *
-     * Observer callbacks that touch ECS state must declare it via `access`
-     * (merged over an all-empty declaration) — undeclared access throws in
-     * `DEV`, and those decls drive the firing order. `yieldExisting` replays
-     * `onAdd` over current matches on registration. Register at world-build time
-     * (before `startup()`); the returned handle's `dispose()` unregisters.
+     * Keep a change tick for each row of `def`, the row grain of change
+     * detection. `cols.ticksRead(def)` and `changed(def).forEachChunk` read it
+     * against `cols.since`, and every write path stamps it: `setField`, `ref`,
+     * a cursor, `markChanged`, and a store into `cols.ticks(def)`. An `onSet`
+     * observer with entity granularity turns it on as well. Costs one word for
+     * each row of every archetype that holds `def`, and one store on each by-id
+     * write. Never turned off. Idempotent. A sparse component keeps one tick
+     * for each entity index instead, read through `ctx.sparseChanged`.
      */
-    observe(def: ComponentHandle, config: StructuralObserverConfig): ObserverHandle;
-    observe(def: ComponentHandle, config: EntitySetObserverConfig): ObserverHandle;
-    observe(def: ComponentHandle, config: ArchetypeSetObserverConfig): ObserverHandle;
+    trackRows(def: ComponentHandle | SparseComponentDef): void;
     /**
      * Stamp every SAB-backed archetype's live `length` into its SAB
      * descriptor's `row_count` field. **You usually don't need to call
-     * this directly** — `update()` publishes at tick start and
+     * this directly**, `update()` publishes at tick start and
      * `SystemContext.flush()` publishes at every phase boundary, so any
      * WASM scan running inside the schedule sees fresh counts for free.
      * This is an escape hatch for code that mutates archetype state
@@ -589,34 +629,13 @@ export declare class ECS implements QueryResolver {
      *
      * Cheap: walks the descriptor region once, does no column I/O.
      */
-    publishArchetypeRowCounts(): void;
+    publishRowCounts(): void;
     flush(): void;
 }
-/** Archetype closure from a descriptor set.
- *
- * Each descriptor is a system or an observer's synthesized `SystemDescriptor`
- * — both carry `spawns` + `transitions`. Seeds the worklist with every
- * descriptor's `spawns`; iteratively applies every descriptor's `transitions`
- * to every discovered mask whose components cover the transition's `whenHas`.
- * Returns the union of seeds + reachable targets, deduplicated by hash-bucketed
- * mask equality.
- *
- * Termination: every transition either monotonically grows the mask (add
- * outpacing remove), monotonically shrinks it, or returns a mask the
- * `seen` map already holds. Because the universe of masks is bounded by
- * `2^|components|` (and in practice the in-tree spawn/transition set is
- * tiny — ~20 masks at most), the worklist is finite and we exit when it
- * empties.
- *
- * Liberal `whenHas` — over-approximation is fine; an
- * unreachable transition target costs one descriptor row at the SAB tail,
- * not column bytes. Empty `spawns` + `transitions` short-circuit to zero.
- */
-declare function computeArchetypeClosure(descriptors: Iterable<SystemDescriptor>): BitSet[];
-/** @internal — test seam for the closure walk. Exposed so the prewarm
- * tests can exercise the BFS without standing up a full Store. */
+/** @internal, test seam for the closure walk that `archetype_closure.ts`
+ * holds. Exposed so the prewarm tests can exercise the walk without standing
+ * up a full Store. */
 export declare const _ecsInternals: {
     computeArchetypeClosure: typeof computeArchetypeClosure;
 };
-export {};
 //# sourceMappingURL=ecs.d.ts.map