@oasys/oecs 0.5.2 → 0.5.4

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

@@ -6,7 +6,7 @@ import { SystemContext } from './query.cjs';
 import { StructuralObserverEvents } from './store.cjs';
 import { SystemAccessDeclaration, SystemDescriptor } from './system.cjs';
 /** What the observer registry needs from `Store` — the typed seam replacing
- * bare underscore-convention reach-through (M1). `Store` implements this; the
+ * bare underscore-convention reach-through. `Store` implements this; the
  * registry holds only this view, so the compiler bounds what observer dispatch
  * can touch. Underscore names are kept so `Store`'s members stay one
  * declaration (they read as "internal" at every other call site). */
@@ -40,12 +40,12 @@ export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => v
 interface ObserverConfigBase {
     onAdd?: ObserverFn;
     onRemove?: ObserverFn;
-    /** Fires when an entity carrying this component is *disabled* (#577) — at the
-     * deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
+    /** Fires when an entity carrying this component is *disabled* — at the
+     * deferred toggle drain, once per net transition. Mirrors `onRemove`:
      * a disable is a soft remove of the whole mask from default queries. An immediate
      * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
     onDisable?: ObserverFn;
-    /** Fires when an entity carrying this component is *enabled* (#577), symmetric
+    /** Fires when an entity carrying this component is *enabled*, symmetric
      * with `onDisable` / `onAdd`. */
     onEnable?: ObserverFn;
     /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
@@ -56,7 +56,7 @@ interface ObserverConfigBase {
      * semantics), for order-independence of register-vs-spawn. */
     yieldExisting?: boolean;
     /** Diagnostic label for this observer, surfaced by the frame-trace seam
-     * (ADR-0030) as the `observer_fired.observer` field — the same role a system's
+     * as the `observer_fired.observer` field — the same role a system's
      * `name` plays. Optional and observe-only: it never touches `stateHash` or
      * dispatch. Defaults to `observer(<component debug name>)` when the component
      * was registered with a name, else `observer(<cid>)`. */
@@ -64,7 +64,7 @@ interface ObserverConfigBase {
 }
 /** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
  * from the opt-in per-row dirty list (registering this enables dirty tracking
- * for the component — the ADR-0012 list + dedup bit). */
+ * for the component — the dirty list + dedup bit). */
 export interface EntitySetObserverConfig extends ObserverConfigBase {
     onSet: ObserverFn;
     granularity: "entity";
@@ -115,7 +115,7 @@ export declare class ObserverRegistry {
      * registration order (`dispose()` splices entries out, so none are stale).
      * Fed into the `startup()` archetype-prewarm closure so an observer's declared
      * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
-     * system's do (#768). Without this an observer-spawned/-transitioned archetype
+     * system's do. Without this an observer-spawned/-transitioned archetype
      * first-touches lazily mid-tick — the one asymmetry left in the otherwise
      * uniform "no lazy archetypes" prewarm. */
     descriptors(): SystemDescriptor[];
@@ -163,8 +163,8 @@ export declare class ObserverRegistry {
 /**
  * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
  * passes), in place. This is the canonical within-observer order — *never* a
- * comparator `Array.sort`, which the bench measured at 2–4× the entire flush
- * (`observer_dispatch_probe.ts`). Distinct live entities have distinct indices,
+ * comparator `Array.sort`, which the bench measured as much slower than the
+ * entire flush. Distinct live entities have distinct indices,
  * so index order is a total canonical order. `out` is scratch (grown to length);
  * `c0` / `c1` are 1024-entry histograms (reused).
  */

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

@@ -6,7 +6,7 @@ import { SystemContext } from './query.js';
 import { StructuralObserverEvents } from './store.js';
 import { SystemAccessDeclaration, SystemDescriptor } from './system.js';
 /** What the observer registry needs from `Store` — the typed seam replacing
- * bare underscore-convention reach-through (M1). `Store` implements this; the
+ * bare underscore-convention reach-through. `Store` implements this; the
  * registry holds only this view, so the compiler bounds what observer dispatch
  * can touch. Underscore names are kept so `Store`'s members stay one
  * declaration (they read as "internal" at every other call site). */
@@ -40,12 +40,12 @@ export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => v
 interface ObserverConfigBase {
     onAdd?: ObserverFn;
     onRemove?: ObserverFn;
-    /** Fires when an entity carrying this component is *disabled* (#577) — at the
-     * deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
+    /** Fires when an entity carrying this component is *disabled* — at the
+     * deferred toggle drain, once per net transition. Mirrors `onRemove`:
      * a disable is a soft remove of the whole mask from default queries. An immediate
      * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
     onDisable?: ObserverFn;
-    /** Fires when an entity carrying this component is *enabled* (#577), symmetric
+    /** Fires when an entity carrying this component is *enabled*, symmetric
      * with `onDisable` / `onAdd`. */
     onEnable?: ObserverFn;
     /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
@@ -56,7 +56,7 @@ interface ObserverConfigBase {
      * semantics), for order-independence of register-vs-spawn. */
     yieldExisting?: boolean;
     /** Diagnostic label for this observer, surfaced by the frame-trace seam
-     * (ADR-0030) as the `observer_fired.observer` field — the same role a system's
+     * as the `observer_fired.observer` field — the same role a system's
      * `name` plays. Optional and observe-only: it never touches `stateHash` or
      * dispatch. Defaults to `observer(<component debug name>)` when the component
      * was registered with a name, else `observer(<cid>)`. */
@@ -64,7 +64,7 @@ interface ObserverConfigBase {
 }
 /** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
  * from the opt-in per-row dirty list (registering this enables dirty tracking
- * for the component — the ADR-0012 list + dedup bit). */
+ * for the component — the dirty list + dedup bit). */
 export interface EntitySetObserverConfig extends ObserverConfigBase {
     onSet: ObserverFn;
     granularity: "entity";
@@ -115,7 +115,7 @@ export declare class ObserverRegistry {
      * registration order (`dispose()` splices entries out, so none are stale).
      * Fed into the `startup()` archetype-prewarm closure so an observer's declared
      * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
-     * system's do (#768). Without this an observer-spawned/-transitioned archetype
+     * system's do. Without this an observer-spawned/-transitioned archetype
      * first-touches lazily mid-tick — the one asymmetry left in the otherwise
      * uniform "no lazy archetypes" prewarm. */
     descriptors(): SystemDescriptor[];
@@ -163,8 +163,8 @@ export declare class ObserverRegistry {
 /**
  * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
  * passes), in place. This is the canonical within-observer order — *never* a
- * comparator `Array.sort`, which the bench measured at 2–4× the entire flush
- * (`observer_dispatch_probe.ts`). Distinct live entities have distinct indices,
+ * comparator `Array.sort`, which the bench measured as much slower than the
+ * entire flush. Distinct live entities have distinct indices,
  * so index order is a total canonical order. `out` is scratch (grown to length);
  * `c0` / `c1` are 1024-entry histograms (reused).
  */

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

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

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

@@ -6,13 +6,13 @@ import { ComponentDef, ComponentHandle, ComponentID, MutableColumnsForSchema, Co
 import { SparseComponentDef, SparseComponentID, SparseSchemaOf } 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 { ComponentCursor, ComponentRef, ReadonlyComponentCursor, 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
+ * underscore members `ecs.ts` and the query internals reach. `Store`
+ * implements this; when the cache/driver layer is extracted 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. */
@@ -25,7 +25,7 @@ export interface QueryHost {
      * 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). */
+     * archetype lists rebuild when their observed epoch is stale. */
     readonly _queryDirtyEpoch: number;
     /** Record a per-entity onSet dirty mark for `def` (gated by
      * `_anyDirtyTracked` at the call site). */
@@ -33,11 +33,11 @@ export interface QueryHost {
     /** 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). */
+    /** Second query-match path: sparse-term intersection. */
     _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). */
+    /** Third query-match path: the `(*, T)` wildcard. */
     _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). */
+    /** Fourth query-match path: hierarchy depth ordering. */
     _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 {
@@ -46,7 +46,7 @@ export interface QueryCacheEntry {
     anyOfMask: BitSet | null;
     query: Query<any>;
 }
-/** One owner for every query-resolution cache (M2). Previously the dedup
+/** One owner for every query-resolution cache. 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
@@ -84,10 +84,10 @@ export interface QueryResolver {
     _getCurrentTick(): number;
     _getQueryDirtyEpoch(): number;
     _nextQueryId(): number;
-    /** All query-resolution caches — dedup + composition (M2). One owner; see
+    /** All query-resolution caches — dedup + composition. 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
+    /** Second query-match path: 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
@@ -95,18 +95,18 @@ export interface QueryResolver {
      * 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). */
+     * all rows. */
     _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
+     * (`withRelation`) 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
+    /** Third query-match path: `(*, 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 +
+    /** Fourth query-match path: 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
@@ -115,10 +115,10 @@ export interface QueryResolver {
      * 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
+/** No depth limit on a `.hierarchy(R)` term — 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
+/** A `.hierarchy(R)` depth-ordering term. 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. */
@@ -143,10 +143,10 @@ export declare class ChunkColumns<out Defs extends 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). */
+     * `def` must be a term of the iterating query. */
     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). */
+     * `def` must be a term of the iterating query. */
     read<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): ColumnsForSchema<SchemaOf<D>>;
 }
 export declare class Query<Defs extends readonly ComponentDef[]> {
@@ -173,7 +173,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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
+     * 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
@@ -181,7 +181,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     private _isDenseOnly;
     /** First matching entity, or `undefined` when the query matches none — the
      * singleton read (`player`, `camera`) without hand-rolling a forEach +
-     * closure capture (POLISH_AUDIT M8). Dense-only queries answer from the
+     * closure capture. 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
@@ -197,16 +197,16 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     /** 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
+     * default, or all rows when `includeDisabled`. Reads the partition
      * fields directly (not the archetype's flag-dependent `entityCount`
      * getter). */
     get entityCount(): number;
     get archetypes(): readonly ArchetypeView<Defs>[];
-    /** Carry this query's non-dense terms — optional fetch-if-present (#575) and
-     * sparse membership (#469) — onto a freshly composed dense query. `and` /
+    /** Carry this query's non-dense terms — optional fetch-if-present and
+     * sparse membership — 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
+     * 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
@@ -216,7 +216,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     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
+    /** @internal — cold cache-miss path for single-arg `and`, split out 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
@@ -225,9 +225,9 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     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`. */
+    /** @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
      * iterated via `forEachEntity`, never `forEach` (sparse members are
@@ -237,11 +237,11 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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
+    /** Exclude a sparse component: 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`. */
+     * multi-arg form folds over this — 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` /
@@ -250,19 +250,19 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * Carries the existing `_optional` terms through unchanged (the two axes
      * compose). */
     private _deriveSparse;
-    /** Require the `(R, *)` wildcard (#579): match only sources that hold **any**
+    /** 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).
+     * 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). */
+     * Cached per `(parent_id, relation_id)` like the sparse terms. */
     withRelation(...defs: RelationDef[]): Query<Defs>;
     private _withRelationOne;
-    /** Exclude the `(R, *)` wildcard (#579): drop sources that hold any target
+    /** Exclude the `(R, *)` wildcard: 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>;
@@ -274,7 +274,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     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
+     * deeper than `maxDepth` (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
@@ -284,8 +284,8 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      *
      * 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
+     * sparse term). **Exclusive relations only** (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`).
@@ -298,13 +298,13 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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` /
      * `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 +
+     * `(*, 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
      * here rather than as a chained term because it is a runtime `EntityID`: baking
@@ -315,13 +315,13 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * `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
+    /** 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
      * `_carryNondense`), so it survives composition in any order. Returns a new
@@ -338,7 +338,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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
+    /** 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`
@@ -347,8 +347,8 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * carried through `and`/`not`/`anyOf` like the sparse/optional terms. */
     includeDisabled(): Query<Defs>;
     forEach(cb: (arch: ArchetypeView<Defs>) => void): void;
-    /** @internal — cold `includeDisabled` wrapper for `forEach` (#577), split out
-     * (#649) so the all-rows flag dance (`_setIterAllRows` + try/finally) stays
+    /** @internal — cold `includeDisabled` wrapper for `forEach`, split out
+     * 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;
@@ -399,15 +399,15 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     forEachUntil(cb: (arch: ArchetypeView<Defs>) => boolean): boolean;
     /** @internal — shared body for `forEachUntil`'s default and
      * `includeDisabled` paths. Same dev-mode optional-term scope as
-     * `forEach` (#592). */
+     * `forEach`. */
     private _forEachUntilInner;
-    /** @internal — the `includeDisabled` delegate for `forEach` (#577). The
+    /** @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
+     * 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
+     * (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
@@ -428,7 +428,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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`
+     * the cached one in place. `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
@@ -441,7 +441,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      * 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
+    /** @internal — cold rebuild path for `_nonEmpty`, split out 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
@@ -450,7 +450,7 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
     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`. */
+    /** @internal — cold cache-miss path for single-arg `anyOf`; see `_andMiss`. */
     private _anyOfMiss;
     /** Create a ChangedQuery that filters archetypes by change tick.
      *
@@ -461,11 +461,11 @@ export declare class Query<Defs extends readonly ComponentDef[]> {
      *  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`/
+     *  The returned ChangedQuery is composable: `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`. */
+    /** @internal — cold cache-miss path for single-arg `changed`; see `_andMiss`. */
     private _changedMiss;
     /** @internal — reads lastRunTick from the resolver (ECS). */
     _ctxLastRunTick(): number;
@@ -508,7 +508,7 @@ export type DeclaredBundleOrDef<D> = [D] extends [unknown] ? D extends Component
     readonly values: Readonly<Partial<FieldValues<SchemaOf<D>>>>;
 } : never : never;
 /**
- * Deferred structural-command facade (§ctx.commands — Bevy `Commands`).
+ * Deferred structural-command facade (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
@@ -553,7 +553,7 @@ export declare class Commands<out A extends SystemAccess = SystemAccess> {
     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).
+    /** Buffer `entityId` to be disabled at the phase flush (idempotent).
      * 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
@@ -583,11 +583,11 @@ export declare class Commands<out A extends SystemAccess = SystemAccess> {
 export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
     private readonly store;
     lastRunTick: number;
-    /** Deferred structural-command facade (§ctx.commands). */
+    /** Deferred structural-command facade. */
     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
+    /** The world's frame-trace sink, 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;
@@ -596,7 +596,7 @@ export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
     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
+     *: `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;
@@ -609,8 +609,8 @@ export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
      * 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,
+     * Record an entity as changed for a component's per-entity `onSet` observer.
+     * 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
@@ -631,11 +631,32 @@ export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
      * 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.
+     * written through a deliberate cast. See ref.ts.
      */
     refRead<D extends ComponentDef<any>>(def: D & DeclaredRead<A, D>, entityId: EntityID): ReadonlyComponentRef<SchemaOf<D>>;
+    /**
+     * A re-pointable single-entity cursor over `def` — the in-system twin of
+     * {@link ECS.cursor}, and the accessor to reach for when a system touches many
+     * entities **by id** rather than by query span.
+     *
+     * `ctx.ref` allocates one accessor for each entity. That allocation is the
+     * largest part of the cost of a read of one field by id, because to make an
+     * accessor costs much more than to move one. Make the cursor one time,
+     * outside the loop:
+     *
+     *   const p = ctx.cursor(Pos);
+     *   for (const e of hits) { p.at(e); p.x += p.y * dt; }
+     *
+     * Mutable: every `at()` stamps the change tick. Still prefer `eachChunk` when
+     * a query can express the entity set — a cursor removes the per-entity
+     * allocation, not the per-entity archetype resolution.
+     */
+    cursor<D extends ComponentDef<any>>(def: D & DeclaredWrite<A, D>): ComponentCursor<SchemaOf<D>>;
+    /** Read-only {@link cursor}: no change-tick stamp on `at()`. Advisory only,
+     * same caveat as `ctx.refRead`. */
+    cursorRead<D extends ComponentDef<any>>(def: D & DeclaredRead<A, D>): ReadonlyComponentCursor<SchemaOf<D>>;
     /** Whether `entityId` is currently disabled (immediate read). Toggling is
-     * deferred — `ctx.commands.disable` / `ctx.commands.enable` (#577). */
+     * deferred — `ctx.commands.disable` / `ctx.commands.enable`. */
     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;
@@ -660,12 +681,12 @@ export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
      *  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
+     *  `ECS.update()` also republishes once at tick start, which covers
+     *  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
+     *  is materially cheaper than the earlier pattern of paying it per
+     *  WASM-using system per tick. The descriptor walk is now gated
      *  on a dirty flag, so read-only phases skip the walk entirely. */
     flush(): void;
     /**
@@ -702,7 +723,7 @@ export declare class SystemContext<out A extends SystemAccess = SystemAccess> {
      * 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-
+    /** Drop a resource mid-tick. 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. */
@@ -722,11 +743,11 @@ export declare class ChangedQuery<Defs extends readonly ComponentDef[]> {
     /** 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. */
+    /** @internal — cold `includeDisabled` wrapper, split out of `forEach`
+     * 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
+    /** @internal — the `includeDisabled` delegate for `forEach`. The
+     * default path inlines this body directly into `forEach` 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;