@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,415 +1,304 @@
-import { Store } from './store.cjs';
-import { FrameTraceSink } from './frame_trace.cjs';
 import { Archetype, ArchetypeView } from './archetype.cjs';
 import { EntityID } from './entity.cjs';
-import { ComponentDef, ComponentHandle, ComponentID, MutableColumnsForSchema, ColumnsForSchema, AttachValuesArg, SchemaOf, FieldValues, DeclaredQueryTerm } from './component.cjs';
-import { SparseComponentDef, SparseComponentID, SparseSchemaOf } from './sparse_store.cjs';
+import { ComponentDef } from './component.cjs';
+import { SparseComponentDef } from './sparse_store.cjs';
 import { RelationDef } from './relation.cjs';
-import { SystemAccess, DeclaredRead, DeclaredWrite, DeclaredAdd, DeclaredRemove, DeclaredSparseRead, DeclaredSparseWrite, DeclaredRelationRead, DeclaredRelationWrite, DeclaredResourceRead, DeclaredResourceWrite, DespawnArg } from './system.cjs';
-import { ComponentRef, ReadonlyComponentRef } from './ref.cjs';
-import { EventKey, EventReader, EventShape, SignalKey } from './event.cjs';
-import { ResourceKey, ResourceValueOf } from './resource.cjs';
 import { BitSet } from '../../type_primitives/index.cjs';
-/** 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>>;
-}
+import { ArchetypeTerm, QueryTerms } from './query_terms.cjs';
+import { QueryResolver } from './query_cache.cjs';
+import { ChunkColumns } from './chunk_columns.cjs';
+import { ChangedQuery } from './changed_query.cjs';
 export declare class Query<Defs extends readonly ComponentDef[]> {
     private readonly _archetypes;
-    readonly _defs: Defs;
+    readonly defs: Defs;
     private readonly _resolver;
-    readonly _include: BitSet;
+    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
+    readonly id: number;
+    readonly terms: QueryTerms;
+    readonly includesDisabled: boolean;
+    constructor(archetypes: Archetype[], defs: Defs, resolver: QueryResolver, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, id: number, terms?: QueryTerms);
+    /** Guard the dense-only methods `entityCount`, `archetypeCount`, `forEach`,
+     * `forEachChunk` and `some` against a query carrying sparse terms. These
+     * walk the dense archetype
+     * list and never consult `sparseIncludes` or `sparseExcludes`, so on a
+     * sparse-derived query they would 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
+     * honors sparse membership. Mirrors `ChangedQuery`'s dev-guard on its
      * include-mask invariant. */
     private _assertDenseOnly;
-    /** Whether this query carries only dense terms — the precondition for the
+    /** Refuse a reader that answers from the unfiltered dense list. Three do:
+     * `archetypeCount`, `archetypes` and `excludeWords`. Each would report the
+     * archetypes the mask picked and not the ones the term kept, which is a
+     * wider set and a wrong answer. Dev-only, and prod keeps the reader. */
+    private _assertNoArchetypeTerm;
+    /** Whether this query carries only dense terms, the precondition for the
      * archetype-walk fast paths (`entityCount`, `firstEntity`, `singleEntity`). */
     private _isDenseOnly;
-    /** First matching entity, or `undefined` when the query matches none — the
+    /** 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
+     * closure capture. Dense-only queries answer from the
+     * first non-empty archetype in O(archetypes). A query with a sparse, relation
+     * or hierarchy term falls 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
+     * 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. */
+    /** 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
+    /** Total entity count across all matching archetypes, enabled rows only by
+     * default, or all rows when `includeDisabled`. Reads the partition
      * fields directly (not the archetype's flag-dependent `entityCount`
      * getter). */
     get entityCount(): number;
+    /** @internal The exclude-mask as raw words, or `null` when the query has no
+     * `not` term. A worker resolves the matched archetypes from the masks
+     * alone, so the parallel plan carries these words to the pool. */
+    get excludeWords(): readonly number[] | null;
     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)`
+    /** Carry this query's non-dense terms, optional fetch-if-present and
+     * sparse membership, onto a freshly composed dense query. `and`,
+     * `not` and `or` 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. An earlier version silently dropped them, which made 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. */
+     * 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
+    /** @internal, cold cache-miss path for single-arg `and`, split out so
+     * the hot `and` body is only 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`. */
+     * function (the `query_compose` shape). Same rationale for `_notMiss`,
+     * `_orMiss` and `_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`. */
+    not(...comps: ComponentDef[]): Query<Defs>;
+    /** @internal, cold cache-miss path for single-arg `not`. See `_andMiss`. */
     private _notMiss;
-    /** Require a sparse component (#469): match only entities that hold it,
+    /** Require a sparse component: 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
+     * 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
+    andSparse(...defs: SparseComponentDef[]): Query<Defs>;
+    /** One-id `andSparse` 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;
+    private _andSparseOne;
+    /** Exclude a sparse component: drop entities that hold it. Same
+     * dense-list reuse and `forEachEntity` iteration as `andSparse`. */
+    notSparse(...defs: SparseComponentDef[]): Query<Defs>;
+    /** One-id `notSparse` composition, cached on `(parent_id, sparseId)`. The
+     * multi-arg form folds over this, mirrors `_andSparseOne`. */
+    private _notSparseOne;
     /** 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
+     * dense state by reference, the masks are never mutated in place (`and`,
+     * `not` and `or` 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
+     * Carries the existing `optionalTerms` terms through unchanged (the two axes
      * compose). */
     private _deriveSparse;
-    /** Require the `(R, *)` wildcard (#579): match only sources that hold **any**
+    /** Narrow the matched archetypes by an expression, or by a term a plugin
+     * built.
+     *
+     * A chained term asks one flat question of the mask. An expression nests,
+     * so `q.where(or(and(Pos, Vel), Frozen))` says what no chain says. Build it
+     * from the free `and`, `or` and `not`, which take a component definition as
+     * a leaf and each other as a node.
+     *
+     * A plugin supplies its own `ArchetypeTerm` instead, and `where` accepts it
+     * on the same footing.
+     *
+     * It composes both ways. `q.where(t).not(D)` and `q.not(D).where(t)`
+     * are the same set, because the derive threads the terms record forward the
+     * way every other non-dense term is threaded.
+     *
+     * What it costs. One predicate call per archetype, per query, at the
+     * rebuild the store's dirty epoch triggers. `forEach`, `forEachChunk` and
+     * `forEachEntity` are untouched: they walk the list the rebuild produced.
+     *
+     * What it refuses. `archetypeCount`, `archetypes` and `excludeWords` all
+     * answer from the unfiltered dense list, so a term-carrying query refuses
+     * them in a dev build rather than answering too wide.
+     *
+     * Cached per (term, parent query), so a repeated call gives one instance. */
+    where(term: ArchetypeTerm): Query<Defs>;
+    /** Require the `(R, *)` wildcard: 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
+     * R's backing sparse store (exclusive `{target}` row and multi tag), so this is a
+     * relation-typed front door over `andSparse`. It pushes R's backing sparse
+     * id onto `sparseIncludes` and reuses the `forEachEntity` sparse-match path
+     * (insertion order, canonical sorting is reserved for `stateHash` and the
+     * snapshot, and costs much more here for no determinism benefit).
+     * 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;
+     * Cached per `(parent_id, relation_id)` like the sparse terms. */
+    andRelation(...defs: RelationDef[]): Query<Defs>;
+    private _andRelationOne;
+    /** Exclude the `(R, *)` wildcard: drop sources that hold any target
+     * under `R`. Mirror of `andRelation` on the exclude side (pushes R's
+     * backing sparse id onto `sparseExcludes`). */
+    notRelation(...defs: RelationDef[]): Query<Defs>;
+    private _notRelationOne;
     /** 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`. */
+     * ids (which only the `DEV` access check consumes), reusing the dense,
+     * optional and 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
+     * exclusive relation `R`, parents before children, and (optionally) drop any
+     * deeper than `maxDepth` (flecs `cascade`, bitECS `Hierarchy()`). The
+     * matched set is unchanged, still the dense mask plus the sparse, `(R, *)`
+     * and disabled terms. `.hierarchy(R)` only reorders and 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
+     * 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
+     * no SoA column span, and `forEach` and `entityCount` reject a hierarchy query (like
+     * a sparse term). Exclusive relations only, which matches the traversal
+     * constraint. 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`).
+     * `and`, `not` and `or` 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. */
+     * `Defs` is unchanged, `R` is an ordering, not a required component (like
+     * `not` and `or`). 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`. */
+     * query's dense, sparse, optional, disabled and 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` /
+     * system's `relationReads`. Iteration-time (`forEachEntity` and
      * `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 +
+     * built outside a system, same rationale as the data-op checks. `DEV` only
+     * outside a system `assertRelationRead` is a no-op. */
+    private _assertRelationAccess;
+    /** Iterate every source related to `target` under **any** relation, the
+     * `(*, T)` wildcard, 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
+     * order (the `sourcesOf` and `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
+     * query-ids, and `(*, T)` is the rare or cold shape. Composes with
+     * `andRelation`, `andSparse` and 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. */
+     * `relationReads: [ANY_RELATION]` (plus `[R]` for any composed `andRelation`).
+     * Cold and 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
+    /** Add optional fetch-if-present terms. 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
+     * not declared here, 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
+     * span). The term is carried through `and`, `not` and `or` (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. */
+     * `not` and `or`). 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). */
+     * resolver's shared single-term map (dense cid < 128, same packing as the
+     * `and`, `not` and `or` 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`. */
+     * existing sparse terms through unchanged, same rationale as `_deriveSparse`. */
     private _deriveOptional;
-    /** Opt this query back in to disabled entities (#577). By default a query
+    /** Opt this query back in to disabled entities. 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
+     * reports `length`, and `entityCount` and `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. */
+     * carried through `and`, `not` or `or` like the sparse or 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
+    /** @internal, cold `includeDisabled` wrapper for `forEach`, split out
+     * so the all-rows flag dance (`_setIterAllRows` inside a `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
+     * Per-archetype destructured column iteration, the flecs
+     * `run()` model and the koota `useStores` model, and the recommended hot-path default for
      * mutating systems:
      *
-     *   q.eachChunk((cols, count) => {
+     *   q.forEachChunk((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`
+     * vs the raw path it replaces (per-field `getColumnMut` + manual `ecsTick`
      * thread + `entityCount` loop). It folds away: per-field fetches (one call
-     * per component), the `getColumn`/`getColumnRead` choice (→ `.mut`/`.read`),
+     * per component), the `getColumnMut` and `getColumnRead` choice (→ `.mut` and `.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`.
+     * column accessor reachable through the iteration path, the read-only
+     * `ArchetypeView` from `forEach` deliberately omits the mutable `getColumnMut`.
      * 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`).
+     * disabled tail). Dense-only like `forEach`, so a sparse, relation or
+     * hierarchy term throws 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)
+    forEachChunk(cb: (cols: ChunkColumns<Defs>, count: number) => void): void;
+    /** @internal, shared body for `forEachChunk`'s default and `includeDisabled`
+     * paths. The `ChunkColumns` cursor is allocated per call (a small object whose
+     * cost does not scale with the per-row work) rather than cached on the query, so
+     * a nested `forEachChunk` on the same query gets its own cursor instead of
+     * re-pointing the outer pass's `arch` and `tick`. The per-(archetype, component)
      * column-group caches that actually matter for allocation live on the
      * `Archetype`, untouched. */
-    private _eachChunkInner;
+    private _forEachChunkInner;
     /**
      * 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
+     * "does any matching row satisfy X?", without it, callers hand-rolled a
+     * `query.archetypes` walk (re-implementing the empty-archetype skip) only
      * 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
+    some(cb: (arch: ArchetypeView<Defs>) => boolean): boolean;
+    /** @internal, shared body for `some`'s default and
      * `includeDisabled` paths. Same dev-mode optional-term scope as
-     * `forEach` (#592). */
-    private _forEachUntilInner;
-    /** @internal — the `includeDisabled` delegate for `forEach` (#577). The
+     * `forEach`. */
+    private _someInner;
+    /** @internal, the `includeDisabled` delegate for `forEach`. 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. */
+     * to dodge a megamorphic delegate hop. This copy survives only for the
+     * rare all-rows path, which needs the `_setIterAllRows` `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
+     * (the sparse-membership match path). Use this whenever the query
+     * carries a `andSparse` or a `notSparse` 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.
@@ -419,316 +308,78 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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),
+     * traversal. This is sharper than for dense `forEach`. `ctx.addSparse` and
+     * `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
+    /** @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 —
+     * the cached one in place. `forEach`, `entityCount` and `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
+     * then re-enters here via a nested `forEach` or `entityCount`. 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
+     * allocation per epoch advance, and only on a boundary crossing. 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
+    nonEmptyArchs(): Archetype[];
+    /** @internal, cold rebuild path for `nonEmptyArchs`, split out so the
+     * hot `nonEmptyArchs` body is only an epoch check + cached return. Keeping the
+     * filter loops here shrinks `nonEmptyArchs`'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
+     * `query_compose` shape): the leaner `nonEmptyArchs` keeps `forEach` under V8's
      * per-function cumulative inlining budget. */
     private _rebuildNonEmpty;
+    /** @internal, the rebuild of a query that carries plugin archetype terms.
+     * Same non-empty filter as `_rebuildNonEmpty`, with every term consulted
+     * for each surviving archetype. Separate body so a query with no term
+     * never loads a term list. */
+    private _rebuildFiltered;
     /** 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;
+    or(...comps: ComponentDef[]): Query<Defs>;
+    /** @internal, cold cache-miss path for single-arg `or`. See `_andMiss`. */
+    private _orMiss;
     /** 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.
+     *  `forEach` works at archetype grain, not row grain: the store stamps
+     *  `changedTick[cid]` per archetype on any write into that component's
+     *  column (`Archetype.changedTick` in archetype.ts). One changed row trips
+     *  `forEach` on the whole archetype next tick. For row grain, iterate with
+     *  `forEachChunk` and read `cols.ticksRead(def)`, which needs
+     *  `ecs.trackRows(def)`.
      *
-     *  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)`. */
+     *  A stamp is reported once. The change tick advances before every
+     *  system run, so a stamp made by an earlier system this frame is above
+     *  the reader's last run, and a stamp the reader already saw is not.
+     *
+     *  The returned ChangedQuery is composable. `and`, `not`, `or` and
+     *  `optional` refine it further, so `q.changed(Pos).not(Dead)` works, and
+     *  is the same set as `q.not(Dead).changed(Pos)`. */
     changed(...defs: ComponentDef[]): ChangedQuery<Defs>;
-    /** @internal — cold cache-miss path for single-arg `changed` (#649); see `_andMiss`. */
+    /** @internal, cold cache-miss path for single-arg `changed`. See `_andMiss`. */
     private _changedMiss;
-    /** @internal — reads lastRunTick from the resolver (ECS). */
-    _ctxLastRunTick(): number;
+    /** @internal, reads lastRunTick from the resolver (ECS). */
+    lastRunTick(): number;
+    /** @internal, the change tick, for a `ChangedQuery` chunk pass. */
+    changeTick(): number;
+    /** @internal, the resolver, for a `ChangedQuery` chunk pass. */
+    resolver(): QueryResolver;
+    /** @internal, the dense-only guard, for a `ChangedQuery` chunk pass. */
+    assertDenseOnly(op: string): void;
 }
 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.
- *
- * The inner `D extends ComponentDef ? … : never` DISTRIBUTES over the declared
- * add-set union, so each raw-literal branch carries its OWN def's schema
- * (`Partial<FieldValues<SchemaOf<D>>>`) rather than the erased
- * `Partial<Record<string, number>>`. A hand-written `{ def: Vel, values: { x }}`
- * whose fields don't match its def is then rejected in a DECLARED-ACCESS system
- * — matching the `StrictBundles` guarantee on the `ecs.*` surface. A PERMISSIVE
- * context (`add: ComponentDef<any>`, i.e. an unnarrowed / `exclusive` system)
- * keeps the loose shape, which is the point of opting out of narrowing. The
- * outer no-op is preserved, so the variance invariant above still holds
- * (verified: the `permissiveHelper(ctx)` assertion still compiles).
- */
-export type DeclaredBundleOrDef<D> = [D] extends [unknown] ? D extends ComponentDef ? D | {
-    readonly def: D;
-    readonly values: Readonly<Partial<FieldValues<SchemaOf<D>>>>;
-} : never : 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>;
-    /** Read a resource (declared in `resourceReads`). The flat `ctx` surface verbs
-     * its accessors — `getResource`/`setResource`/`removeResource`/`hasResource`,
-     * matching `getField`/`setField`/`hasComponent`. The grouped `ecs.resources`
-     * facade drops the noun (`get`/`set`/`remove`/`has`) because its receiver
-     * already names it. */
-    getResource<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;
+    /** Require these components. The first link of the chain takes the same
+     * word as every later link, so `qb.and(Pos).and(Vel)` and `qb.and(Pos, Vel)`
+     * read alike and mean one thing. */
+    and<T extends ComponentDef[]>(...defs: T): Query<T>;
 }
 //# sourceMappingURL=query.d.ts.map