@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,718 @@
+import { Store } from './store.js';
+import { FrameTraceSink } from './frame_trace.js';
+import { Archetype, ArchetypeView } from './archetype.js';
+import { EntityID } from './entity.js';
+import { ComponentDef, ComponentHandle, ComponentID, MutableColumnsForSchema, ColumnsForSchema, AttachValuesArg, SchemaOf, DeclaredQueryTerm } from './component.js';
+import { SparseComponentDef, SparseComponentID, SparseSchemaOf } from './sparse_store.js';
+import { RelationDef } from './relation.js';
+import { SystemAccess, DeclaredRead, DeclaredWrite, DeclaredAdd, DeclaredRemove, DeclaredSparseRead, DeclaredSparseWrite, DeclaredRelationRead, DeclaredRelationWrite, DeclaredResourceRead, DeclaredResourceWrite, DespawnArg } from './system.js';
+import { ComponentRef, ReadonlyComponentRef } from './ref.js';
+import { EventKey, EventReader, EventShape, SignalKey } from './event.js';
+import { ResourceKey, ResourceValueOf } from './resource.js';
+import { BitSet } from '../../type_primitives/index.js';
+/** The query-driver seam on `Store` — the typed contract behind the
+ * underscore members `ecs.ts` and the query internals reach (M1). `Store`
+ * implements this; when the cache/driver layer is extracted (M2/H1) the
+ * interface retargets at the collaborator without touching consumers.
+ * `_tick` / `_trace` are deliberately mutable: `ECS.update()` advances the
+ * change tick and `ECS.setTrace` installs the sink through this seam. */
+export interface QueryHost {
+    /** Change tick — advanced by `ECS.update()` each frame. */
+    _tick: number;
+    /** Dev-only frame-trace sink (`ECS.setTrace`); always null in prod. */
+    _trace: FrameTraceSink | null;
+    /** True once any component observer opted into per-entity dirty tracking —
+     * gates `_noteSet` at every write site. */
+    readonly _anyDirtyTracked: boolean;
+    /** Bumped when an archetype crosses empty↔non-empty — cached query
+     * archetype lists rebuild when their observed epoch is stale (#327). */
+    readonly _queryDirtyEpoch: number;
+    /** Record a per-entity onSet dirty mark for `def` (gated by
+     * `_anyDirtyTracked` at the call site). */
+    _noteSet(def: ComponentHandle, eid: EntityID): void;
+    /** Dev-only: buffered event count across dirty channels (mid-update emit
+     * detection in `ECS.update()`). */
+    _devBufferedEventCount(): number;
+    /** Second query-match path: sparse-term intersection (#469 / ADR-0011). */
+    _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;
+    /** Third query-match path: the `(*, T)` wildcard (#579). */
+    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    /** Fourth query-match path: hierarchy depth ordering (#581). */
+    _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;
+}
+export interface QueryCacheEntry {
+    includeMask: BitSet;
+    excludeMask: BitSet | null;
+    anyOfMask: BitSet | null;
+    query: Query<any>;
+}
+/** One owner for every query-resolution cache (M2). Previously the dedup
+ * bucket map lived on `ECS` while `Query` populated eleven composition maps
+ * declared on the resolver interface — ownership split across two modules.
+ * All entries are structural (a query is minted once per unique term set and
+ * lives for the world's lifetime; components and queries are never
+ * unregistered), so there is no invalidation lifecycle — the maps are
+ * append-only. Key encodings are unchanged from the pre-extraction fields.
+ *
+ * The composition maps are exposed as readonly fields (not per-kind accessor
+ * pairs): the mutation protocol is uniform (`get` → miss → build → `set`) and
+ * hot enough that composition sites keep direct map access; the invariant
+ * this class carries is single ownership, not access mediation. */
+export declare class QueryCache {
+    private readonly dedup;
+    readonly andSingle: Map<number, Query<any>>;
+    readonly notSingle: Map<number, Query<any>>;
+    readonly anyOfSingle: Map<number, Query<any>>;
+    readonly changedSingle: Map<number, ChangedQuery<any>>;
+    readonly optionalSingle: Map<number, Query<any>>;
+    readonly withSparseSingle: Map<number, Query<any>>;
+    readonly withoutSparseSingle: Map<number, Query<any>>;
+    readonly withRelationSingle: Map<number, Query<any>>;
+    readonly withoutRelationSingle: Map<number, Query<any>>;
+    readonly includeDisabledSingle: Map<number, Query<any>>;
+    readonly hierarchySingle: Map<number, Query<any>>;
+    /** Dedup lookup: bucket scan with full mask equality (buckets are
+     * typically 1–2 entries). */
+    findDedup(key: number, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null): QueryCacheEntry | undefined;
+    /** Record a freshly minted query under its dedup key. */
+    addDedup(key: number, entry: QueryCacheEntry): void;
+}
+export interface QueryResolver {
+    _resolveQuery(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, defs: readonly ComponentDef[]): Query<any>;
+    _getLastRunTick(): number;
+    /** Current ECS write tick — the tick `eachChunk` stamps via `cols.mut` (§eachChunk). */
+    _getCurrentTick(): number;
+    _getQueryDirtyEpoch(): number;
+    _nextQueryId(): number;
+    /** All query-resolution caches — dedup + composition (M2). One owner; see
+     * `QueryCache` for the per-map keying/id-space notes. */
+    readonly _caches: QueryCache;
+    /** Second query-match path (#469 / ADR-0011): drive iteration by sparse
+     * membership rather than the archetype mask, yielding entities — sparse
+     * members are scattered across archetypes, so there is no archetype-column
+     * span to hand back. With a sparse require term, drive from the smallest
+     * required store and filter; with only sparse excludes, drive the dense
+     * archetype list and skip excluded rows; with neither, walk dense entities.
+     * Only entered via `Query.forEachEntity`, so dense `forEach` never pays.
+     * `includeDisabled` widens the per-archetype row scan from enabled rows to
+     * all rows (#577). */
+    _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;
+    /** Backing sparse id of a relation — resolves a `(R, *)` wildcard term
+     * (`withRelation`, #579) to the membership store the sparse-match path
+     * already drives. */
+    _relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** Third query-match path (#579): `(*, T)` — drive iteration from the union of
+     * every relation's `sourcesOf(target)` (dedup + canonical sort), intersected
+     * with the dense mask + sparse terms + the enabled-row filter. Only entered via
+     * `Query.forEachRelatedTo`. */
+    _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    /** Fourth query-match path (#581): yield the matched entities (dense mask +
+     * sparse terms + enabled-row filter, exactly the `_forEachSparseMatch`
+     * intersection) in canonical **hierarchy depth order** over exclusive relation
+     * `relation` — depth ascending (parents before children), entity index
+     * ascending within a depth band. Entities deeper than `maxDepth` are skipped
+     * (`HIERARCHY_UNBOUNDED` = no limit). Only entered via `Query.forEachEntity`
+     * on a query carrying a `.hierarchy(R)` term. */
+    _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;
+}
+/** No depth limit on a `.hierarchy(R)` term (#581) — yield every matched entity
+ * regardless of its depth in the tree. The default `maxDepth`. */
+export declare const HIERARCHY_UNBOUNDED: number;
+/** A `.hierarchy(R)` depth-ordering term (#581). Records the exclusive relation
+ * whose tree defines the order and the (optional) max depth to yield. Stored on
+ * the Query and consumed by the `forEachEntity` hierarchy match path; absent
+ * (`null`) for the common case. */
+export interface HierarchyTerm {
+    /** The exclusive relation whose chain/tree defines the depth ordering. */
+    readonly relation: RelationDef;
+    /** Inclusive max depth to yield (root = 0); entities deeper than this are
+     * skipped. `HIERARCHY_UNBOUNDED` for no limit (bitECS `Hierarchy()` depth arg). */
+    readonly maxDepth: number;
+}
+/**
+ * eachChunk cursor (§eachChunk). One instance is allocated per `eachChunk`
+ * pass and reused across every matched archetype in that pass — only `_arch`/
+ * `_tick` are re-pointed per archetype, so the inner loop allocates nothing.
+ * Per-call (not cached on the query) so a nested `eachChunk` on the same query
+ * gets its own cursor and can't re-point an outer pass's position. `.mut(def)` /
+ * `.read(def)` resolve a whole component's columns at once into a field-keyed
+ * object (a per-archetype-per-component cache refreshed in place), hiding the
+ * change tick. Destructure the group immediately; don't retain it across calls.
+ */
+export declare class ChunkColumns<out Defs extends readonly ComponentDef<any>[] = readonly ComponentDef<any>[]> {
+    /** @internal */ _arch: Archetype;
+    /** @internal */ _tick: number;
+    /** Mutable column group — `const { x, y } = cols.mut(Pos)`. Stamps the tick.
+     * `def` must be a term of the iterating query (POLISH_AUDIT #6). */
+    mut<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): MutableColumnsForSchema<SchemaOf<D>>;
+    /** Read-only column group — `const { vx, vy } = cols.read(Vel)`. No tick bump.
+     * `def` must be a term of the iterating query (POLISH_AUDIT #6). */
+    read<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): ColumnsForSchema<SchemaOf<D>>;
+}
+export declare class Query<Defs extends readonly ComponentDef[]> {
+    private readonly _archetypes;
+    readonly _defs: Defs;
+    private readonly _resolver;
+    readonly _include: BitSet;
+    private readonly _exclude;
+    private readonly _anyOf;
+    private _nonEmptyArchetypes;
+    private _lastSeenEpoch;
+    readonly _id: number;
+    readonly _sparseInclude: readonly SparseComponentID[];
+    readonly _sparseExclude: readonly SparseComponentID[];
+    readonly _optional: readonly ComponentID[];
+    readonly _includeDisabled: boolean;
+    readonly _relationIncludes: readonly RelationDef[];
+    readonly _relationExcludes: readonly RelationDef[];
+    readonly _hierarchy: HierarchyTerm | null;
+    constructor(archetypes: Archetype[], defs: Defs, resolver: QueryResolver, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, id: number, sparseInclude?: readonly SparseComponentID[], sparseExclude?: readonly SparseComponentID[], optional?: readonly ComponentID[], includeDisabled?: boolean, relationIncludes?: readonly RelationDef[], relationExcludes?: readonly RelationDef[], hierarchy?: HierarchyTerm | null);
+    /** Guard the dense-only methods (`count` / `forEach` / `archetype_count`)
+     * against a query carrying sparse terms. These walk the dense archetype
+     * list and never consult `_sparseInclude` / `_sparseExclude`, so on a
+     * sparse-derived query they'd **fail open** — returning the unfiltered dense
+     * result instead of the sparse-filtered one. Throw in `DEV` (compiled
+     * out of prod) steering the caller to `forEachEntity`, the only path that
+     * honors sparse membership (#469). Mirrors `ChangedQuery`'s dev-guard on its
+     * include-mask invariant. */
+    private _assertDenseOnly;
+    /** Whether this query carries only dense terms — the precondition for the
+     * archetype-walk fast paths (`count`, `firstEntity`, `singleEntity`). */
+    private _isDenseOnly;
+    /** First matching entity, or `undefined` when the query matches none — the
+     * singleton read (`player`, `camera`) without hand-rolling a forEach +
+     * closure capture (POLISH_AUDIT M8). Dense-only queries answer from the
+     * first non-empty archetype in O(archetypes); queries with sparse /
+     * relation / hierarchy terms fall back to a full `forEachEntity` walk.
+     * "First" is iteration order, not spawn order — with more than one match
+     * the pick is arbitrary (use `singleEntity` to assert uniqueness). */
+    firstEntity(): EntityID | undefined;
+    /** The query's one matching entity. Dev-throws `QUERY_NOT_SINGLETON` when
+     * the match count is 0 or >1 — the singleton assertion for entities that
+     * must be unique (player, camera). Prod skips the count and returns the
+     * first match (`undefined` if none). */
+    singleEntity(): EntityID;
+    /** Count for non-dense queries — full `forEachEntity` walk. */
+    private _countViaWalk;
+    /** Number of matching archetypes (including empty ones). */
+    get archetypeCount(): number;
+    /** Total entity count across all matching archetypes — enabled rows only by
+     * default, or all rows when `includeDisabled()` (#577). Reads the partition
+     * fields directly (not the archetype's flag-dependent `entityCount`
+     * getter). */
+    get entityCount(): number;
+    get archetypes(): readonly ArchetypeView<Defs>[];
+    /** Carry this query's non-dense terms — optional fetch-if-present (#575) and
+     * sparse membership (#469) — onto a freshly composed dense query. `and` /
+     * `not` / `anyOf` build the new dense mask via `_resolveQuery`, which is
+     * keyed on the mask alone and so hands back a query carrying NONE of these
+     * terms; before #592 that silently dropped them, making composition
+     * order-dependent (`q.optional(V).and(H)` lost `V`; `q.and(H).optional(V)`
+     * kept it). When this query carries no non-dense terms (the common case)
+     * `base` is already correct and returned as-is, preserving the mask-cached
+     * singleton with zero allocation. Otherwise re-derive on top of `base`'s dense
+     * state, threading the terms forward so composition is symmetric regardless of
+     * order. Reading `base`'s private fields is allowed — same-class instance. */
+    private _carryNondense;
+    /** Extend required component set. Returns a new (cached) Query. */
+    and<D extends ComponentDef[]>(...comps: D): Query<[...Defs, ...D]>;
+    /** @internal — cold cache-miss path for single-arg `and`, split out (#649) so
+     * the hot `and` body is just key-compute + cache hit. The miss path runs once
+     * per unique composition, then every repeat is a cache hit; keeping it out of
+     * line shrinks `and`'s inlined footprint when several composes share one hot
+     * function (the `query_compose` shape). Same rationale for `_notMiss` /
+     * `_anyOfMiss` / `_changedMiss`. */
+    private _andMiss;
+    /** Exclude archetypes that have any of these components. */
+    without(...comps: ComponentDef[]): Query<Defs>;
+    /** @internal — cold cache-miss path for single-arg `not` (#649); see `_andMiss`. */
+    private _notMiss;
+    /** Require a sparse component (#469): match only entities that hold it,
+     * across every archetype. A sparse term doesn't touch the dense mask, so
+     * the returned (cached) query reuses this one's live archetype list; it is
+     * iterated via `forEachEntity`, never `forEach` (sparse members are
+     * scattered within archetypes, so there is no SoA column span to yield). */
+    withSparse(...defs: SparseComponentDef[]): Query<Defs>;
+    /** One-id `withSparse` composition, cached on `(parent_id, sparseId)` in
+     * the resolver's shared single-term map. Both the single- and multi-arg public
+     * forms fold over this, so all sparse-require composition is deduplicated. */
+    private _withSparseOne;
+    /** Exclude a sparse component (#469): drop entities that hold it. Same
+     * dense-list reuse and `forEachEntity` iteration as `withSparse`. */
+    withoutSparse(...defs: SparseComponentDef[]): Query<Defs>;
+    /** One-id `withoutSparse` composition, cached on `(parent_id, sparseId)`. The
+     * multi-arg form folds over this (#497) — mirrors `_withSparseOne`. */
+    private _withoutSparseOne;
+    /** Build a derived query carrying new sparse terms. Reuses this query's
+     * dense state by reference — the masks are never mutated in place (`and` /
+     * `not` / `anyOf` copy before mutating), and `_archetypes` is the same
+     * live array the store appends to, so the derived query stays live too.
+     * Carries the existing `_optional` terms through unchanged (the two axes
+     * compose). */
+    private _deriveSparse;
+    /** Require the `(R, *)` wildcard (#579): match only sources that hold **any**
+     * target under relation `R`. "Has any `(R, *)` pair" is exactly membership in
+     * R's backing sparse store (exclusive `{target}` row / multi tag), so this is a
+     * relation-typed front door over `withSparse` — it pushes R's backing sparse
+     * id onto `_sparseInclude` and reuses the `forEachEntity` sparse-match path
+     * (insertion order; canonical sorting is reserved for `stateHash`/snapshot, and
+     * costs 4–5× here for no determinism benefit — see the §579 bench report).
+     * Membership semantics: each source once; fetch its targets with
+     * `ctx.targetsOf(e, R)`. Requires `relationReads: [R]` (checked at iteration).
+     * Cached per `(parent_id, relation_id)` like the sparse terms (#497). */
+    withRelation(...defs: RelationDef[]): Query<Defs>;
+    private _withRelationOne;
+    /** Exclude the `(R, *)` wildcard (#579): drop sources that hold any target
+     * under `R`. Mirror of `withRelation` on the exclude side (pushes R's
+     * backing sparse id onto `_sparseExclude`). */
+    withoutRelation(...defs: RelationDef[]): Query<Defs>;
+    private _withoutRelationOne;
+    /** Build a derived query carrying new relation-wildcard terms. Threads the
+     * backing-sparse ids (which the driver actually consumes) plus the relation
+     * ids (which only the `DEV` access check consumes), reusing the dense /
+     * optional / disabled state by reference — same rationale as `_deriveSparse`. */
+    private _deriveRelation;
+    /** Order this query's matched entities in **hierarchy depth order** over the
+     * exclusive relation `R` — parents before children — and (optionally) drop any
+     * deeper than `maxDepth` (#581; flecs `cascade` / bitECS `Hierarchy()`). The
+     * matched *set* is unchanged (still the dense mask + sparse + `(R, *)` + disabled
+     * terms); `.hierarchy(R)` only **reorders** + depth-limits it, so an entity with
+     * no `R`-parent is a root at depth 0 and still yielded (first). The canonical
+     * order is depth ascending, then **entity index ascending within each depth
+     * band** — a total, insertion-order-independent order (identical across lockstep
+     * peers), produced by an O(K) radix on the entity index, never a comparator sort.
+     *
+     * Iterate with `forEachEntity`: members scatter across archetypes, so there is
+     * no SoA column span — `forEach` / `count` reject a hierarchy query (like a
+     * sparse term). **Exclusive relations only** (matches the traversal constraint
+     * #474); a multi relation throws `RELATION_MODE_MISMATCH` at iteration, and a
+     * cycle is a loud `RELATION_CYCLE` in `DEV` (a safe break in production).
+     * Requires `relationReads: [R]` (checked at iteration). Carried through
+     * `and`/`not`/`anyOf` like the sparse terms (`_carryNondense`).
+     *
+     * `Defs` is unchanged — `R` is an ordering, not a required component (like
+     * `not` / `anyOf`). Returns a new query; the unbounded form is cached. */
+    hierarchy(relation: RelationDef<"exclusive">, maxDepth?: number): Query<Defs>;
+    /** Build a derived query carrying a hierarchy ordering term. Reuses this
+     * query's dense / sparse / optional / disabled / relation-wildcard state by
+     * reference (the matched set is unchanged) — same rationale as `_deriveSparse`. */
+    private _deriveHierarchy;
+    /** Assert every `(R, *)` wildcard term on this query was declared in the
+     * system's `relationReads` (#579 / #496). Iteration-time (`forEachEntity` /
+     * `forEachRelatedTo`), not construction-time, so it is robust to queries
+     * built outside a system — same rationale as the data-op checks. `DEV` only;
+     * outside a system `checkRelationRead` is a no-op. */
+    private _checkRelationAccess;
+    /** Iterate every source related to `target` under **any** relation — the
+     * `(*, T)` wildcard (#579) — intersected with this query's dense + sparse +
+     * `(R, *)` + disabled predicate, each source yielded once in ascending-EntityID
+     * order (the `sourcesOf` / `sourcesOfAny` convention). `target` is supplied
+     * here rather than as a chained term because it is a runtime `EntityID`: baking
+     * it into a cached `Query` would key the cache on a recycled value and churn
+     * query-ids, and `(*, T)` is the rare/cold shape. Composes with
+     * `withRelation` / `withSparse` / dense terms on the receiver. Reads
+     * every relation's reverse index, so the system must declare
+     * `relationReads: [ANY_RELATION]` (plus `[R]` for any composed `withRelation`).
+     * Cold/structural — not a per-tick hot loop over many targets. */
+    forEachRelatedTo(target: EntityID, cb: (entityId: EntityID) => void): void;
+    /** Add optional fetch-if-present terms (#575). Does NOT narrow the matched
+     * set — the dense mask is untouched, so iteration still spans archetypes with
+     * and without each `T`. Read each column per archetype span via
+     * `arch.getOptionalColumnRead(T, field)` (column when present, `undefined`
+     * when absent). `.optional(T)` is the *declaration* that authorizes that fetch:
+     * inside `forEach`, `getOptionalColumnRead` throws in `DEV` if `T` was
+     * not declared here (#592) — the read-side analog of `reads:[T]`, which is also
+     * still required for access coverage (both checks fire, even on the absent
+     * span). The term is carried through `and`/`not`/`anyOf` (see
+     * `_carryNondense`), so it survives composition in any order. Returns a new
+     * (cached) Query.
+     *
+     * `Defs` is unchanged (the optional `T` is not a required component, like
+     * `not` / `anyOf`); column types come from the accessor's own generics. */
+    optional(...defs: ComponentDef[]): Query<Defs>;
+    /** One-id `optional` composition, cached on `(parent_id << 16) | cid` in the
+     * resolver's shared single-term map (dense cid <= 128, same packing as the
+     * `and` / `not` / `anyOf` caches). */
+    private _optionalOne;
+    /** Build a derived query carrying new optional terms. Reuses this query's
+     * dense state by reference (the matched set is unchanged) and carries the
+     * existing sparse terms through unchanged — same rationale as `_deriveSparse`. */
+    private _deriveOptional;
+    /** Opt this query back in to disabled entities (#577). By default a query
+     * excludes disabled entities (the iteration bound `arch.entityCount` is the
+     * enabled-row count). The returned (cached) query spans disabled rows too:
+     * `forEach` publishes the all-rows flag so the SoA loop's `arch.entityCount`
+     * reports `length`, and `count`/`forEachEntity` widen accordingly. Does NOT
+     * touch the dense mask, so it reuses this query's live archetype list and is
+     * carried through `and`/`not`/`anyOf` like the sparse/optional terms. */
+    includeDisabled(): Query<Defs>;
+    forEach(cb: (arch: ArchetypeView<Defs>) => void): void;
+    /** @internal — cold `includeDisabled` wrapper for `forEach` (#577), split out
+     * (#649) so the all-rows flag dance (`_setIterAllRows` + try/finally) stays
+     * out of `forEach`'s inlined hot body. The default (enabled-only) query never
+     * reaches here, so V8 leaves this uninlined and `forEach` shrinks accordingly. */
+    private _forEachIncludeDisabled;
+    /**
+     * Per-archetype destructured column iteration (§eachChunk) — the flecs
+     * `run()` / koota `useStores` model, and the recommended hot-path default for
+     * mutating systems:
+     *
+     *   q.eachChunk((cols, count) => {
+     *     const { x, y }   = cols.mut(Pos);   // whole group, tick stamped inside
+     *     const { vx, vy } = cols.read(Vel);  // read-only group
+     *     for (let i = 0; i < count; i++) { x[i] += vx[i] * dt; y[i] += vy[i] * dt; }
+     *   });
+     *
+     * vs the raw path it replaces (per-field `getColumn` + manual `ecsTick`
+     * thread + `entityCount` loop). It folds away: per-field fetches (one call
+     * per component), the `getColumn`/`getColumnRead` choice (→ `.mut`/`.read`),
+     * the manual tick arg (hidden in `.mut`), and the `.length`-vs-`entityCount`
+     * corruption trap (`count` is `entityCount`). It is also the only mutable
+     * column accessor reachable through the iteration path — the read-only
+     * `ArchetypeView` from `forEach` deliberately omits the mutable `getColumn`.
+     * The SoA inner loop is byte-identical, and the per-archetype group objects
+     * are cached (zero per-archetype allocation). One `ChunkColumns` cursor is
+     * allocated per pass and reused across that pass's archetypes. Honours
+     * `includeDisabled()` exactly like `forEach` (the bound widens to the
+     * disabled tail); dense-only like `forEach` (sparse/relation/hierarchy terms
+     * throw in `DEV` — iterate those with `forEachEntity`).
+     */
+    eachChunk(cb: (cols: ChunkColumns<Defs>, count: number) => void): void;
+    /** @internal — shared body for `eachChunk`'s default and `includeDisabled`
+     * paths. The `ChunkColumns` cursor is allocated per call (a 2-field object whose
+     * cost doesn't scale with the per-row work) rather than cached on the query, so
+     * a nested `eachChunk` on the SAME query gets its own cursor instead of
+     * re-pointing the outer pass's `_arch`/`_tick`. The per-(archetype, component)
+     * column-group caches that actually matter for allocation live on the
+     * `Archetype`, untouched. */
+    private _eachChunkInner;
+    /**
+     * Early-exit iteration: like `forEach`, but stops as soon as `cb` returns
+     * `true`, and returns whether any callback did. The predicate analog for
+     * "does any matching row satisfy X?" — without it, callers hand-rolled a
+     * `query.archetypes` walk (re-implementing the empty-archetype skip) just
+     * to be able to `return` mid-scan. Deliberately a separate method:
+     * honouring return values on `forEach`'s existing `=> void` callback
+     * would silently change behaviour for arrow-expression bodies that happen
+     * to return a truthy value.
+     */
+    forEachUntil(cb: (arch: ArchetypeView<Defs>) => boolean): boolean;
+    /** @internal — shared body for `forEachUntil`'s default and
+     * `includeDisabled` paths. Same dev-mode optional-term scope as
+     * `forEach` (#592). */
+    private _forEachUntilInner;
+    /** @internal — the `includeDisabled` delegate for `forEach` (#577). The
+     * default (enabled-only) path inlines this body directly into `forEach`
+     * (#608) to dodge a megamorphic delegate hop; this copy survives only for the
+     * rare all-rows path, which needs the `_setIterAllRows` try/finally wrap. */
+    private _forEachInner;
+    /** Iterate the entities this query matches, yielding each `EntityID`
+     * (#469 — the sparse-membership match path). Use this whenever the query
+     * carries a `withSparse` / `withoutSparse` term: members are scattered
+     * across archetypes, so there is no SoA column span to hand back — read
+     * fields via `ctx.getField` (dense) or `ctx.getSparseField` (sparse) on
+     * the yielded entity. A dense-only query also works here (it walks its
+     * archetypes' entity ids), but prefer `forEach` for the SoA hot loop.
+     *
+     * Iteration is read-mostly: mutating the *driving* sparse component's
+     * membership mid-iteration is unsafe. The walk drives off the store's live
+     * key array, so **adding** the driving component (the store `push`es a new
+     * key, which the `i < length` loop then visits) and **removing** it (the
+     * store swap-pops, shifting the index list under the walk) both corrupt the
+     * traversal. This is sharper than for dense `forEach`: `ctx.addSparse` /
+     * `ctx.addRelation` apply *immediately* (no archetype transition to defer),
+     * so unlike a deferred dense `addComponent` the mutation lands in the live
+     * array at once. Buffer such edits and apply them after the walk. */
+    forEachEntity(cb: (entityId: EntityID) => void): void;
+    /** @internal — used by ChangedQuery. Rebuild non-empty archetype list if the
+     * Store has bumped its dirty epoch since our last rebuild, return cached result.
+     *
+     * Rebuild allocates a *fresh* array and swaps it in rather than truncating
+     * the cached one in place (#431). `forEach`/`count`/`ChangedQuery.forEach`
+     * bind the returned array once and walk it; an in-place `dst.length = 0` +
+     * re-push would corrupt that walk if the query is re-entrantly iterated —
+     * i.e. the callback runs an immediate-mode mutation that crosses a
+     * 0↔non-zero entity boundary on the *same* Query (bumping the epoch) and
+     * then re-enters here via a nested `forEach`/`count`. Building fresh hands
+     * the inner call its own array and leaves the outer iterator's snapshot
+     * intact, so each archetype is visited exactly once. Cost is one array
+     * allocation per epoch advance (rare — only on boundary crossings); the
+     * steady-state path returns the cached array with zero allocation. In-system
+     * iteration never triggers a rebuild mid-loop: deferred mutations settle the
+     * epoch during `flushStructural`, between systems. */
+    _nonEmpty(): Archetype[];
+    /** @internal — cold rebuild path for `_nonEmpty`, split out (#649) so the
+     * hot `_nonEmpty` body is just an epoch check + cached return. Keeping the
+     * filter loops here shrinks `_nonEmpty`'s inlined bytecode footprint, which
+     * matters when several composed queries iterate inside one hot function (the
+     * `query_compose` shape): the leaner `_nonEmpty` keeps `forEach` under V8's
+     * per-function cumulative inlining budget. */
+    private _rebuildNonEmpty;
+    /** Require at least one of these components. */
+    anyOf(...comps: ComponentDef[]): Query<Defs>;
+    /** @internal — cold cache-miss path for single-arg `anyOf` (#649); see `_andMiss`. */
+    private _anyOfMiss;
+    /** Create a ChangedQuery that filters archetypes by change tick.
+     *
+     *  Granularity is **archetype**, not row: the `_changedTick[cid]` is
+     *  bumped per archetype on any write into that component's column
+     *  (`Archetype._changedTick` in archetype.ts). A 1-row write in a
+     *  1000-row archetype trips `forEach` on the whole archetype next tick.
+     *  Use cases that need row-level granularity should compare per-row
+     *  state explicitly inside the callback.
+     *
+     *  The returned ChangedQuery is composable (M6): `and`/`without`/`anyOf`/
+     *  `optional` refine it further, so `q.changed(Pos).without(Dead)` works — and
+     *  is the same set as `q.without(Dead).changed(Pos)`. */
+    changed(...defs: ComponentDef[]): ChangedQuery<Defs>;
+    /** @internal — cold cache-miss path for single-arg `changed` (#649); see `_andMiss`. */
+    private _changedMiss;
+    /** @internal — reads lastRunTick from the resolver (ECS). */
+    _ctxLastRunTick(): number;
+}
+export declare class QueryBuilder {
+    private readonly _resolver;
+    constructor(_resolver: QueryResolver);
+    with<T extends ComponentDef[]>(...defs: T): Query<T>;
+}
+/**
+ * A `BundleOrDef` whose def is constrained to the enclosing system's declared
+ * add surface (§typestate). The bundle branch restates `Bundle`'s shape with
+ * the def slot narrowed — intersecting `Bundle<any> & { def: … }` instead
+ * would put two `ComponentDef` instantiations in one intersection, which TS
+ * relates leniently (see system.ts §typestate notes).
+ *
+ * The outer conditional is a deliberate no-op (`[D] extends [unknown]` is
+ * always true): it makes the variance of `D` — and therefore of the access
+ * param `A` threaded through `Commands` / `SystemContext` — UNMEASURABLE to
+ * the compiler. A measurable (plain-union) definition here gets `A` marked
+ * reliably contravariant, variance-based comparison then rejects
+ * `SystemContext<Narrow> → SystemContext` without the structural fallback,
+ * and every helper taking a bare `SystemContext` stops accepting typed
+ * contexts. Unmeasurable variance forces the structural path, where class
+ * methods compare bivariantly and the conversion holds.
+ */
+export type DeclaredBundleOrDef<D> = [D] extends [unknown] ? D | {
+    readonly def: D;
+    readonly values: Readonly<Partial<Record<string, number>>>;
+} : never;
+/**
+ * Deferred structural-command facade (§ctx.commands — Bevy `Commands`).
+ * Namespaces the deferred structural ops so the call site is self-documenting:
+ * `ctx.commands.add(e, …)` is *always* deferred (applied at the phase flush),
+ * ending the collision where `ecs.addComponent` (immediate) and a bare
+ * `ctx.addComponent` (deferred) would share a name with opposite timing. Takes
+ * varargs callable bundles, so one shape — `commands.spawn(bundle(Pos,{x,y}), bundle(Vel,{vx:1}))`
+ * — serves spawn and add. This is the ONLY deferred surface: the bare
+ * `ctx.addComponent` / `ctx.removeComponent` / `ctx.disable` / `ctx.enable`
+ * duplicates were removed in 0.5.0, completing the receiver-implies-timing
+ * rule (`ecs.*` immediate, `ctx.commands.*` deferred) that 0.5.0 started for
+ * spawn/despawn.
+ *
+ * `A` narrows the def-taking methods to the enclosing system's declared access
+ * (§typestate, system.ts); the default is fully permissive.
+ *
+ * `out A` (declared covariance) is deliberate: every use of `A` sits inside a
+ * declared-access conditional, whose variance the compiler cannot measure —
+ * left unannotated, the measured verdict rejects `Commands<Narrow> →
+ * Commands` (the direction every permissive consumer needs). Covariance is
+ * the honest direction: a context with MORE declared access is usable where
+ * one with less is expected. The checks themselves are per-instantiation, so
+ * the annotation does not weaken them.
+ */
+export declare class Commands<out A extends SystemAccess = SystemAccess> {
+    private readonly store;
+    constructor(store: Store);
+    /** Spawn from bundles. Create is immediate (the id is returned now); the
+     *  component attaches are deferred to the phase flush — so until that flush the
+     *  entity exists in its empty/partial archetype and a query running later in
+     *  the same phase can observe it half-built. (Same semantics as
+     *  `ctx.commands.spawn()` + `ctx.addComponent`; fully-deferred id-reservation
+     *  spawn, à la Bevy, is a separate follow-up.) */
+    spawn(...items: DeclaredBundleOrDef<A["add"]>[]): EntityID;
+    /** Attach bundles to an existing entity (deferred). Bundles zero-fill
+     * omitted fields. */
+    add(entityId: EntityID, ...items: DeclaredBundleOrDef<A["add"]>[]): this;
+    /** Explicit complete-values attach (deferred) — the compile-checked shape
+     * where a typo'd or missing field is a compile error, mirroring the
+     * immediate `ecs.addComponent(e, def, values)`. Tags take no values
+     * argument (`AttachValuesArg`). */
+    add<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredAdd<A, D>, ...values: AttachValuesArg<SchemaOf<D>>): this;
+    /** Remove a component (deferred). */
+    remove<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredRemove<A, D>): this;
+    /** Destroy an entity (deferred). */
+    despawn(entityId: DespawnArg<A>): this;
+    /** Buffer `entityId` to be disabled at the phase flush (idempotent, #577).
+     * Deferred because a toggle is an in-archetype row swap, which would corrupt
+     * a `forEach` SoA loop iterating that archetype if applied mid-system (it
+     * reorders the dense columns being read). A disabled entity is excluded from
+     * default queries; opt back in per query with `.includeDisabled()`. The
+     * immediate read is `ctx.isDisabled`. */
+    disable(entityId: EntityID): this;
+    /** Buffer `entityId` to be re-enabled at the phase flush (idempotent).
+     * Deferred for the same row-swap reason as `disable`. */
+    enable(entityId: EntityID): this;
+}
+/**
+ * The per-system world facade. `A` is the system's declared access surface
+ * (§typestate, system.ts): the config-form `registerSystem` computes it from
+ * the literal `reads`/`writes`/… declarations and every guarded method below
+ * checks its handle argument against the matching union at compile time —
+ * the same rules `accessCheck` enforces at runtime in `DEV`. The default
+ * `A = SystemAccess` is fully permissive, so a bare `SystemContext` (helper
+ * functions, host-side code, explicitly-annotated escape hatches) behaves
+ * exactly as before, and every narrowed `SystemContext<…>` is assignable to
+ * it.
+ *
+ * `out A` (declared covariance) is deliberate — see `Commands` above: the
+ * declared-access conditionals are unmeasurable to the compiler, and the
+ * unannotated verdict rejects exactly the `SystemContext<Narrow> →
+ * SystemContext` conversion the whole design depends on.
+ */
+export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
+    private readonly store;
+    lastRunTick: number;
+    /** Deferred structural-command facade (§ctx.commands). */
+    readonly commands: Commands<A>;
+    /** Current ECS tick. Use this for write ticks in getColumn. */
+    get ecsTick(): number;
+    /** The world's frame-trace sink (ADR-0030), or `null`. Lets the schedule
+     * fire `systemStart`/`flush*` without reaching into the private store.
+     * Read only under `if (DEV)`; the seam is dead-code-eliminated in prod. */
+    get _trace(): FrameTraceSink | null;
+    constructor(store: Store);
+    isAlive(entityId: EntityID): boolean;
+    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    getField<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredRead<A, D>, field: string & keyof SchemaOf<D>): number;
+    /** Total sibling of {@link getField}, mirroring `ecs.tryGetField`
+     * (POLISH_AUDIT #9): `undefined` when the entity is dead or doesn't hold
+     * the component, instead of a dev throw / prod garbage read. The safe way
+     * to probe-and-read in one call: `ctx.tryGetField(e, Health, "current") ?? 0`. */
+    tryGetField<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredRead<A, D>, field: string & keyof SchemaOf<D>): number | undefined;
+    setField<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredWrite<A, D>, field: string & keyof SchemaOf<D>, value: number): void;
+    /** Read-modify-write one field: `updateField(e, Gold, "value", v => v - cost)`
+     * is the one-line form of the `getField` → compute → `setField` round trip.
+     * Returns the written value. Same access-check and observer semantics as the
+     * two calls it composes (inlined here: the declared-access conditionals on
+     * those methods only resolve per `A` instantiation, so a body where `A` is
+     * still generic cannot call them without casts). */
+    updateField<D extends ComponentDef<any>>(entityId: EntityID, def: D & DeclaredWrite<A, D>, field: string & keyof SchemaOf<D>, fn: (current: number) => number): number;
+    /**
+     * Record an entity as changed for a component's per-entity `onSet` observer
+     * (#517 §1 / ADR-0013). The SoA write idiom — `const col = arch.getColumn(D,
+     * f, tick); col[i] = v` in a tight loop — bypasses the deferred buffer and the
+     * engine never sees the per-element writes, so a per-entity `onSet` consumer
+     * pushes the row here (the bench's winning `tick+list`: raw write + an int
+     * push, fired batched at the post-update detection point — never a per-element
+     * observable setter). No-op for components without a per-entity onSet observer.
+     * `setField` records automatically; this is for the hot `getColumn` loop.
+     */
+    markChanged(entityId: EntityID, def: ComponentDef): void;
+    /**
+     * Create a cached component reference for a single entity. Marks the
+     * component as changed (the mutable default — see `refRead` for the
+     * read-only variant to reach for when you are not mutating). See ref.ts.
+     */
+    ref<D extends ComponentDef<any>>(def: D & DeclaredWrite<A, D>, entityId: EntityID): ComponentRef<SchemaOf<D>>;
+    /**
+     * Create a cached read-only component reference for a single entity. Use
+     * this when you are not mutating. The returned `ReadonlyComponentRef<S>`
+     * is an *advisory* compile-time barrier (no `_changedTick` bump): the
+     * `readonly` typing blocks field writes at the type layer, but the
+     * underlying accessor shares its prototype with `ref()` and can still be
+     * written through a §10c-policed cast. See ref.ts.
+     */
+    refRead<D extends ComponentDef<any>>(def: D & DeclaredRead<A, D>, entityId: EntityID): ReadonlyComponentRef<SchemaOf<D>>;
+    /** Whether `entityId` is currently disabled (immediate read). Toggling is
+     * deferred — `ctx.commands.disable` / `ctx.commands.enable` (#577). */
+    isDisabled(entityId: EntityID): boolean;
+    /** Tags take no values argument; valued schemas require a complete one. */
+    addSparse<D extends SparseComponentDef<any>>(entityId: EntityID, def: D & DeclaredSparseWrite<A, D>, ...values: AttachValuesArg<SparseSchemaOf<D>>): this;
+    removeSparse<D extends SparseComponentDef<any>>(entityId: EntityID, def: D & DeclaredSparseWrite<A, D>): this;
+    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
+    getSparseField<D extends SparseComponentDef<any>>(entityId: EntityID, def: D & DeclaredSparseRead<A, D>, field: string & keyof SparseSchemaOf<D>): number;
+    setSparseField<D extends SparseComponentDef<any>>(entityId: EntityID, def: D & DeclaredSparseWrite<A, D>, field: string & keyof SparseSchemaOf<D>, value: number): void;
+    /** Add a `(R, tgt)` pair to `src` (exclusive replaces, multi adds). */
+    addRelation<D extends RelationDef>(src: EntityID, def: D & DeclaredRelationWrite<A, D>, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`; for multi, omitting `tgt` removes all. */
+    removeRelation<D extends RelationDef>(src: EntityID, def: D & DeclaredRelationWrite<A, D>, tgt?: EntityID): this;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf<D extends RelationDef<"exclusive">>(src: EntityID, def: D & DeclaredRelationRead<A, D>): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf<D extends RelationDef>(src: EntityID, def: D & DeclaredRelationRead<A, D>): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+     * `(entity, def)` order, matching `targetOf` / `targetsOf`. */
+    sourcesOf<D extends RelationDef>(tgt: EntityID, def: D & DeclaredRelationRead<A, D>): EntityID[];
+    /** Whether `src` holds any pair under `R`. */
+    hasRelation(src: EntityID, def: RelationDef): boolean;
+    /** Flush all deferred changes: structural (add/remove) first, then
+     *  destructions. Republishes archetype row counts into the SAB
+     *  descriptor at the end so any WASM scan running in the next phase
+     *  sees fresh `row_count` fields. This is one of two publish sites —
+     *  `ECS.update()` also republishes once at tick start (see PATTERNS.md
+     *  §60), covering host-side mutations between updates. The publish walks
+     *  descriptors only — it doesn't touch column data — and benches at
+     *  sub-microsecond per archetype, so paying it once per phase boundary
+     *  is materially cheaper than the pre-#306 pattern of paying it per
+     *  WASM-using system per tick. After #336 the descriptor walk is gated
+     *  on a dirty flag, so read-only phases skip the walk entirely. */
+    flush(): void;
+    /**
+     * Emit an event (or a payload-less signal) onto its channel. The event is
+     * visible to every system that runs *later* in the same `update()` and is
+     * cleared at the tick's tail — events live exactly one tick, there is no
+     * ack/consume. The channel must have been registered at world setup via
+     * `ecs.events.register(key, fields)` / `registerSignal(key)`.
+     *
+     * @example
+     * const Damaged = eventKey<{ target: EntityID; amount: number }>("Damaged");
+     * ecs.events.register(Damaged, ["target", "amount"]);
+     * // inside a system:
+     * ctx.emit(Damaged, { target: e, amount: 10 });
+     */
+    emit(key: SignalKey): void;
+    emit<S extends EventShape<S>>(key: EventKey<S>, values: NoInfer<S>): void;
+    /**
+     * Read this tick's events on a channel. Returns an SoA reader over
+     * everything emitted *earlier in the same `update()`* — order systems so
+     * readers run after emitters, or they see an empty reader.
+     *
+     * @example
+     * const dmg = ctx.read(Damaged); // SoA columns, one per field
+     * for (let i = 0; i < dmg.length; i++) {
+     *   applyDamage(dmg.target[i], dmg.amount[i]);
+     * }
+     */
+    read<S extends EventShape<S>>(key: EventKey<S>): EventReader<S>;
+    resource<K extends ResourceKey<any>>(key: K & DeclaredResourceRead<A, K>): ResourceValueOf<K>;
+    setResource<K extends ResourceKey<any>>(key: K & DeclaredResourceWrite<A, K>, value: ResourceValueOf<NoInfer<K>>): void;
+    /** Drop a resource mid-tick (#798). A lifecycle mutation, so it is access-
+     * checked as a *write* — the system must declare the key in `resourceWrites`,
+     * which serialises it against readers/writers of the same resource. Fails
+     * closed on a missing key. */
+    removeResource<K extends ResourceKey<any>>(key: K & DeclaredResourceWrite<A, K>): void;
+    hasResource<T>(key: ResourceKey<T>): boolean;
+}
+export declare class ChangedQuery<Defs extends readonly ComponentDef[]> {
+    private readonly _query;
+    private readonly _changedIds;
+    constructor(query: Query<Defs>, changedIds: number[]);
+    /** Also require these components (mirrors `Query.and`). */
+    and<D extends ComponentDef[]>(...comps: D): ChangedQuery<[...Defs, ...D]>;
+    /** Exclude archetypes holding any of these (mirrors `Query.without`). */
+    without(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Require at least one of these (mirrors `Query.anyOf`). */
+    anyOf(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Permit optional-component data access in the loop (mirrors `Query.optional`). */
+    optional(...defs: ComponentDef[]): ChangedQuery<Defs>;
+    forEach(cb: (arch: ArchetypeView<Defs>) => void): void;
+    /** @internal — cold `includeDisabled` wrapper (#577), split out of `forEach`
+     * (#649) so the all-rows flag dance stays out of the inlined hot body. */
+    private _forEachIncludeDisabled;
+    /** @internal — the `includeDisabled` delegate for `forEach` (#577). The
+     * default path inlines this body directly into `forEach` (#608) to dodge a
+     * megamorphic delegate hop; this copy survives only for the rare all-rows
+     * path, which needs the `_setIterAllRows` try/finally wrap. */
+    private _forEachInner;
+}
+//# sourceMappingURL=query.d.ts.map