@oasys/oecs 0.3.0 → 0.4.0

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

@@ -0,0 +1,557 @@
+import { Store } from './store';
+import { FrameTraceSink } from './frame_trace';
+import { Archetype, ArchetypeView } from './archetype';
+import { EntityID } from './entity';
+import { ComponentDef, ComponentID, ComponentSchema, FieldValues, MutableColumnsForSchema, ColumnsForSchema, BundleOrDef } from './component';
+import { SparseComponentDef, SparseComponentID } from './sparse_store';
+import { RelationDef } from './relation';
+import { ComponentRef, ReadonlyComponentRef } from './ref';
+import { EventKey, EventReader, EventSchema, SignalKey } from './event';
+import { ResourceKey } from './resource';
+import { BitSet } from '../../type_primitives';
+export interface QueryCacheEntry {
+    includeMask: BitSet;
+    excludeMask: BitSet | null;
+    anyOfMask: BitSet | null;
+    query: Query<any>;
+}
+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;
+    _andSingleCache: Map<number, Query<any>>;
+    _notSingleCache: Map<number, Query<any>>;
+    _anyOfSingleCache: Map<number, Query<any>>;
+    _changedSingleCache: Map<number, ChangedQuery<any>>;
+    _optionalSingleCache: Map<number, Query<any>>;
+    _withSparseSingleCache: Map<number, Query<any>>;
+    _withoutSparseSingleCache: Map<number, Query<any>>;
+    _withRelationSingleCache: Map<number, Query<any>>;
+    _withoutRelationSingleCache: Map<number, Query<any>>;
+    _includeDisabledSingleCache: Map<number, Query<any>>;
+    _hierarchySingleCache: Map<number, Query<any>>;
+    /** 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 {
+    /** @internal */ _arch: Archetype;
+    /** @internal */ _tick: number;
+    /** Mutable column group — `const { x, y } = cols.mut(Pos)`. Stamps the tick. */
+    mut<S extends ComponentSchema>(def: ComponentDef<S>): MutableColumnsForSchema<S>;
+    /** Read-only column group — `const { vx, vy } = cols.read(Vel)`. No tick bump. */
+    read<S extends ComponentSchema>(def: ComponentDef<S>): ColumnsForSchema<S>;
+}
+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;
+    /** 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 flag-dependent `entityCount` getter). */
+    count(): number;
+    get archetypes(): readonly ArchetypeView[];
+    /** 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, 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) => 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, 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) => 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>;
+}
+/**
+ * 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 the bare
+ * `ctx.addComponent` (deferred) 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. The legacy `ctx.addComponent`/etc. stay for now;
+ * the intent is for `ctx.commands.*` to become the only deferred surface.
+ */
+export declare class Commands {
+    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.createEntity` + `ctx.addComponent`; fully-deferred id-reservation
+     *  spawn, à la Bevy, is a separate follow-up.) */
+    spawn(...items: BundleOrDef[]): EntityID;
+    /** Attach bundles to an existing entity (deferred). */
+    add(entityId: EntityID, ...items: BundleOrDef[]): this;
+    /** Remove a component (deferred). */
+    remove(entityId: EntityID, def: ComponentDef): this;
+    /** Destroy an entity (deferred). */
+    despawn(entityId: EntityID): this;
+    /** Disable an entity (deferred). */
+    disable(entityId: EntityID): this;
+    /** Re-enable an entity (deferred). */
+    enable(entityId: EntityID): this;
+}
+export declare class SystemContext {
+    private readonly store;
+    lastRunTick: number;
+    /** Deferred structural-command facade (§ctx.commands). */
+    readonly commands: Commands;
+    /** 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);
+    createEntity(): EntityID;
+    isAlive(entityId: EntityID): boolean;
+    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    getField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S): number;
+    setField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, 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. */
+    updateField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, 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<S extends ComponentSchema>(def: ComponentDef<S>, entityId: EntityID): ComponentRef<S>;
+    /**
+     * 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<S extends ComponentSchema>(def: ComponentDef<S>, entityId: EntityID): ReadonlyComponentRef<S>;
+    /** Buffer an entity for deferred destruction (applied at phase flush). */
+    destroyEntity(id: EntityID): this;
+    addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): this;
+    addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): this;
+    removeComponent(entityId: EntityID, def: ComponentDef): this;
+    /** Buffer `entityId` to be disabled at the phase flush (idempotent). */
+    disable(entityId: EntityID): this;
+    /** Buffer `entityId` to be re-enabled at the phase flush (idempotent). */
+    enable(entityId: EntityID): this;
+    /** Whether `entityId` is currently disabled (immediate read). */
+    isDisabled(entityId: EntityID): boolean;
+    addSparse(entityId: EntityID, def: SparseComponentDef<Record<string, never>>): this;
+    addSparse<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, values: FieldValues<S>): this;
+    removeSparse(entityId: EntityID, def: SparseComponentDef): this;
+    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
+    getSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S): number;
+    setSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S, value: number): void;
+    /** Add a `(R, tgt)` pair to `src` (exclusive replaces, multi adds). */
+    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`; for multi, omitting `tgt` removes all. */
+    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): this;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id. */
+    sourcesOf(def: RelationDef, tgt: EntityID): 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(key: SignalKey): void;
+    emit<S extends EventSchema>(key: EventKey<S>, values: S): void;
+    read<S extends EventSchema>(key: EventKey<S>): EventReader<S>;
+    resource<T>(key: ResourceKey<T>): T;
+    setResource<T>(key: ResourceKey<T>, value: T): 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<T>(key: ResourceKey<T>): 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) => 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/query.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,31 @@
+import { ComponentSchema } from './component';
+import { ArchetypeColumnLayout } from './archetype';
+import { AnyTypedArray, ColumnBacking } from '../../type_primitives';
+/** Maps component schema to scalar get/set properties: { x: number, y: number }. */
+export type ComponentRef<S extends ComponentSchema> = {
+    -readonly [K in keyof S]: number;
+};
+/**
+ * Read-only view of a component reference. This is an **advisory** barrier,
+ * not a runtime safety boundary: the `readonly` properties block field writes
+ * at the type layer, but `createRef` installs working get/set on the shared
+ * prototype for both `ref()` and `refRead()`, so a §10c-policed cast can
+ * still write through (and would skip the change-tick bump `ref()` performs).
+ * Treat it as "I promise I am only reading," enforced by the escape-hatch lint
+ * (`bun run lint:escape-hatches`), not by the runtime.
+ */
+export type ReadonlyComponentRef<S extends ComponentSchema> = {
+    readonly [K in keyof S]: number;
+};
+/** Minimal column group shape needed by createRef. */
+export interface RefColumnGroup {
+    readonly layout: ArchetypeColumnLayout;
+    readonly columns: ColumnBacking<AnyTypedArray>[];
+}
+/**
+ * Create a ComponentRef bound to a specific row in a column group.
+ * The prototype is built once per column group and cached; subsequent
+ * calls for the same group only allocate the lightweight ref object.
+ */
+export declare function createRef<S extends ComponentSchema>(group: RefColumnGroup, row: number): ComponentRef<S>;
+//# sourceMappingURL=ref.d.ts.map

package/dist/core/ecs/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BK;AAEL,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE1E,oFAAoF;AACpF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,IAAI;IACrD,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAChC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,IAAI;IAC7D,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAC/B,CAAC;AAMF,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,EAAE,CAAC;CACjD;AAWD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,eAAe,EAClD,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,MAAM,GACT,YAAY,CAAC,CAAC,CAAC,CAwBjB"}