@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,8 +1,10 @@
-import { Brand, AnyTypedArray, ColumnBacking, TypedArrayTag, BitSet } from '../../type_primitives/index.cjs';
+import { ArchetypeID, ArchetypeView } from './archetype_types.cjs';
+import { AnyTypedArray, ColumnBacking, TypedArrayTag, BitSet } from '../../type_primitives/index.cjs';
 import { ColumnStore } from '../store/column_store.cjs';
-import { ComponentID, ComponentDef, ComponentSchema, SchemaOf, DeclaredQueryTerm, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn } from './component.cjs';
+import { ComponentID, ComponentDef, ComponentSchema, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn } from './component.cjs';
 import { EntityID, ReadonlyEntityIDArray } from './entity.cjs';
-export type ArchetypeID = Brand<number, "archetype_id">;
+import { AccessorColumns } from './ref.cjs';
+export type { ArchetypeID, ArchetypeView } from './archetype_types.cjs';
 export declare const asArchetypeId: (value: number) => ArchetypeID;
 export interface ArchetypeEdge {
     add: ArchetypeID | null;
@@ -16,11 +18,11 @@ export interface ArchetypeEdge {
  * Cached resolution of a *multi*-component add out of this archetype: the
  * target archetype the union lands in, plus the pre-built src→target batch
  * transition map. Keyed (on the source archetype) by an exact N-tagged pack of
- * the added component ids — see `Store.addComponents` (#659).
+ * the added component ids, see `Store.addComponents`.
  *
  * Where `ArchetypeEdge` is the per-*component* edge the single-add path indexes
- * by `edges[component_id]`, this is the per-*set* edge the plural-add path looks
- * up by packed key — folding the mask hash, `archLookup`, and batch-map fetch
+ * by `_edges[component_id]`, this is the per-*set* edge the plural-add path looks
+ * up by packed key, folding the mask hash, `archLookup`, and batch-map fetch
  * the final-mask resolve repeats every call into one `Map.get`. Never
  * invalidated: the archetype graph is monotonic (archetypes outlive the Store).
  */
@@ -33,79 +35,30 @@ export interface ArchetypeColumnLayout {
     fieldNames: string[];
     fieldIndex: Record<string, number>;
     fieldTypes: TypedArrayTag[];
-}
-interface ArchetypeColumnGroup {
-    layout: ArchetypeColumnLayout;
-    columns: ColumnBacking<AnyTypedArray>[];
+    /** The global name id of each field (`fieldGids` in ref.ts). Optional so a
+     * test can build a heap archetype from a bare layout. The archetype then
+     * uses the ordinals as ids, which is correct for an archetype that no ref or
+     * cursor reaches through the shared prototype. */
+    fieldGid?: Int32Array;
 }
 /**
  * Per-column allocator. Returns a `ColumnBacking` for the field at
  * `fieldIdx` of component `component_id`. The default factory (when none
  * is supplied to the constructor) allocates a `GrowableTypedArray` on the
- * heap; `fromColumnStore` supplies a factory that wraps SAB views instead.
+ * heap. `fromColumnStore` supplies a factory that wraps SAB views instead.
  */
 export type ColumnFactory = (componentId: ComponentID, fieldIdx: number, tag: TypedArrayTag) => ColumnBacking<AnyTypedArray>;
 /**
  * Hook the host installs on every SAB-backed archetype so the Archetype
- * can request a SAB grow + refresh from the host BEFORE the insertion
+ * can request a SAB grow + refresh from the host before the insertion
  * that would otherwise throw `StoreColumnOverflowError`. The host (Store)
  * is responsible for running `growColumnStore` and `refreshViews`
- * across every SAB-backed archetype; after the handler returns,
- * `arch._flatColumns[i].buf.length` is guaranteed to be `>= arch.length +
- * additional`. Heap-backed archetypes leave this unset — their
- * `GrowableTypedArray` grows in place. (#171 §6.1.9 Phase 3)
+ * across every SAB-backed archetype. After the handler returns,
+ * `arch.flatColumns[i].buf.length` is guaranteed to be `>= arch.length +
+ * additional`. Heap-backed archetypes leave this unset, their
+ * `GrowableTypedArray` grows in place.
  */
 export type ArchetypeGrowHandler = (arch: Archetype, additional: number) => void;
-/**
- * Public, read-only window onto an archetype's rows. This is the ONLY
- * surface `Query.archetypes`, `Query.forEach`, and `ChangedQuery.forEach`
- * hand to callers — the concrete `Archetype` (with its structural mutators
- * `removeEntity`, `moveEntityFrom`, `writeFields`, `setEdge`, and the
- * mutable `getColumn`) stays internal so query iteration can't bypass the
- * deferred-flush path that prevents iterator invalidation. This is the same
- * back door PR #163 closed for `Store`; issue #378 closed it again for
- * `Query`.
- *
- * `id` is the archetype's opaque identity (not a mutator) — exposed so the
- * public `ECS.batchAddComponent`/`batchRemoveComponent` API can target an
- * archetype without the caller holding a concrete `Archetype` reference.
- */
-export interface ArchetypeView<out Defs extends readonly ComponentDef<any>[] = readonly ComponentDef<any>[]> {
-    /** Opaque archetype identity. Pass to `ECS.batch_*_component`. */
-    readonly id: ArchetypeID;
-    /** Number of **enabled** entities — the default-iteration bound (#577). Rows
-     * `0..entityCount-1` are enabled; disabled rows (if any) sit contiguously at
-     * `entityCount..totalCount-1`. `forEach` SoA loops read this, so they skip
-     * disabled rows for free. Use `totalCount` to span disabled rows too. */
-    readonly entityCount: number;
-    /** Total live rows, enabled + disabled (#577). Equal to `entityCount` unless
-     * some rows are disabled. Use for full-state work (serialization, snapshot,
-     * determinism) that must see every entity regardless of enabled state. */
-    readonly totalCount: number;
-    /** Number of disabled rows = `totalCount - entityCount` (#577). */
-    readonly disabledCount: number;
-    /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
-     * 0..totalCount-1 (enabled rows first, then disabled). */
-    readonly entityIds: ReadonlyEntityIDArray;
-    /** True if this archetype's mask includes the given component. */
-    hasComponent(id: ComponentID): boolean;
-    /** Get a single field's column (read-only). Valid data: indices
-     * 0..entityCount-1. `def` must be a term of the iterating query
-     * (POLISH_AUDIT #6); the bare-`ArchetypeView` default stays permissive. */
-    getColumnRead<D extends ComponentDef<any>, K extends string & keyof SchemaOf<D>>(def: D & DeclaredQueryTerm<Defs, D>, field: K): ReadonlyColumn;
-    /** Tuple fetch of several of one component's columns —
-     * `const [q, r] = arch.getColumnsRead(HexPos, "q", "r")`. One small
-     * array allocation per call; see the class doc on `Archetype`. */
-    getColumnsRead<D extends ComponentDef<any>, const K extends readonly (string & keyof SchemaOf<D>)[]>(def: D & DeclaredQueryTerm<Defs, D>, ...fields: K): {
-        [I in keyof K]: ReadonlyColumn;
-    };
-    /** Get a single field's column **if this archetype has the component**,
-     * else `undefined` — the optional-query fetch-if-present accessor (#575).
-     * The absent branch is expected (resolve the column pointer per archetype
-     * span: present ⇒ column, absent ⇒ `undefined`), not an error. Same
-     * advisory-readonly view and `reads`-access-check as `getColumnRead`. */
-    getOptionalColumnRead<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K): ReadonlyColumn | undefined;
-}
 export declare class Archetype implements ArchetypeView {
     readonly id: ArchetypeID;
     readonly mask: BitSet;
@@ -113,114 +66,220 @@ export declare class Archetype implements ArchetypeView {
     /**
      * Whether a member entity occupies a real row here. True for every archetype
      * except the **empty archetype** (the one with no components), where a
-     * component-less entity is "alive but unplaced" — it points here via
-     * `entityArchetype` but carries `entityRow === UNASSIGNED` and holds no
+     * component-less entity is "alive but unplaced". It points here via
+     * `_entityArchetypes` but carries `_entityRows === UNASSIGNED` and holds no
      * row, exactly like a freshly `createEntity`'d one. Keeping the empty
      * archetype rowless gives a component-less entity a single canonical form
      * regardless of how it got there (created bare vs. lost its last component),
-     * so `stateHash` and zero-require query iteration don't depend on add/remove
+     * so `stateHash` and zero-require query iteration don't depend on add and remove
      * history. The row-materialising methods below honour this flag.
      */
     readonly materializesRows: boolean;
     private readonly _entityIds;
     length: number;
     /**
-     * Enabled/disabled row partition (#577 — entity enable/disable). Rows
+     * Enabled and disabled row partition (entity enable and disable). Rows
      * `[0, enabled_count)` are enabled, `[enabled_count, length)` are disabled.
-     * `enabled_count === length` (no disabled rows) is the common case — every
+     * `enabled_count === length` (no disabled rows) is the common case, every
      * fast path below short-circuits on it, so an archetype that never disables
-     * an entity pays nothing. Disable/enable swap a row across the boundary
-     * (`disableRow`/`enableRow`); appends place enabled rows in front of the
-     * disabled tail (`_placeTail`). `entityCount` (the query/iteration bound)
-     * returns this; `length`/`totalCount` span disabled rows too. Folded into
-     * `stateHash` and published to the SAB descriptor so the WASM sim and
-     * snapshot/restore honour it.
+     * an entity pays nothing. Disable and enable swap a row across the boundary
+     * (`disableRow` and `enableRow`). An append places an enabled row in front of
+     * the disabled tail (`_placeTail`). `entityCount` (the query and iteration bound)
+     * returns this. `length` and `totalCount` span disabled rows too. Folded into
+     * `stateHash` and published to the SAB descriptor so a compute backend and
+     * snapshot and restore honour it.
      */
     enabledCount: number;
     /**
      * Flush-epoch stamp + captured pre-counts for the Store's per-entity flush
-     * 0-crossing detector (#328, #812): `_flushAdds`/`_flushRemoves` stamp each
+     * 0-crossing detector: `_flushAdds` and `_flushRemoves` stamp each
      * archetype on first sight per flush (a few field accesses) instead of probing
-     * a `Map<archetype_id, pre_count>` per entity — the same per-entity Map
-     * cost the destroy drain shed in #457. Both `_flushPreLen` and
-     * `_flushPreEnabled` are recorded so the settle pass can detect a 0-crossing
-     * on either the total (`length`) or the enabled partition (`enabledCount`) —
-     * an enabled append into an all-disabled archetype crosses only the latter
-     * (#812). Owned by Store; pure scheduling bookkeeping, never folded into
+     * a `Map<archetype_id, pre_count>` per entity, the same per-entity Map
+     * cost the destroy drain also avoids. Both `flushPreLen` and
+     * `flushPreEnabled` are recorded so the settle pass can detect a 0-crossing
+     * on either the total (`length`) or the enabled partition (`enabledCount`),
+     * an enabled append into an all-disabled archetype crosses only the latter.
+     * Owned by Store. Pure scheduling bookkeeping, never folded into
      * `stateHash`/snapshot.
      */
-    _flushSeenEpoch: number;
-    _flushPreLen: number;
-    _flushPreEnabled: number;
+    flushSeenEpoch: number;
+    flushPreLen: number;
+    flushPreEnabled: number;
     /**
-     * DEV-only iteration guard: >0 while a dense query iterator (`forEach` /
-     * `eachChunk` / `forEachUntil` / `ChangedQuery.forEach`) is delivering this
-     * archetype to a user callback. The row-removing/reordering primitives
-     * (`removeRow` / `disableRow` / `enableRow`) check it so an immediate
-     * structural mutation from inside the walk — which would swap-remove under
-     * the iterator and silently skip or repeat entities — throws instead.
+     * DEV-only iteration guard: >0 while a dense query iterator delivers this
+     * archetype to a user callback. Those iterators are `forEach`,
+     * `forEachChunk`, `some` and `ChangedQuery.forEach`. The row-removing and
+     * reordering primitives `removeRow`, `disableRow` and `enableRow` check it, so an immediate
+     * structural mutation from inside the walk, which would swap-remove under
+     * the iterator and silently skip or repeat entities, throws instead.
      * Production builds never read or write it.
      */
-    _iterDepth: number;
-    private readonly edges;
+    iterDepth: number;
+    private readonly _edges;
     /**
      * Cache of pre-computed transition maps for multi-component transitions
-     * (this → target). Single-component edges live on `edges[].addMap`/`removeMap`;
-     * multi-component pairs land here. Entries never need invalidation —
+     * (this → target). Single-component edges live on `_edges[].addMap` and `removeMap`
+     * multi-component pairs land here. Entries never need invalidation,
      * archetypes live for the Store's lifetime.
      */
-    private readonly batchTransitionMaps;
+    private readonly _batchTransitionMaps;
     /**
-     * Per-set add-edge cache for `Store.addComponents` (#659), keyed by an
+     * Per-set add-edge cache for `Store.addComponents`, keyed by an
      * exact pack of the added component ids. Lazily allocated: most archetypes
      * never originate a plural add, so the Map stays `null` until the first one
-     * is resolved — the single-add `edges[]` path never touches it.
+     * is resolved, the single-add `_edges[]` path never touches it.
      */
-    private compositeAddEdges;
-    readonly _flatColumns: ColumnBacking<AnyTypedArray>[];
+    private _compositeAddEdges;
+    readonly flatColumns: ColumnBacking<AnyTypedArray>[];
+    bufs: AnyTypedArray[];
+    private _widthBufs;
+    readonly rowTicks: (Uint32Array | undefined)[];
+    private _tickBufs;
+    private _tickCids;
+    private _colKind;
+    private _allF64;
+    private _eids;
+    private _rowCap;
+    private _colCap;
     /** Set by `fromColumnStore` to record which SAB archetype this Archetype
      * draws its column views from. `null` for the default heap-backed path
-     * (no SAB linkage; `refreshViews` would be a no-op there and so
+     * (no SAB linkage, `refreshViews` would be a no-op there and so
      * isn't supported). */
     private _storeArchetypeId;
-    readonly _colOffset: number[];
-    readonly _fieldCount: number[];
+    readonly colOffset: number[];
+    readonly fieldCount: number[];
     private readonly _fieldIndex;
     private readonly _fieldNames;
-    readonly columnGroups: (ArchetypeColumnGroup | undefined)[];
-    readonly _columnIds: number[];
-    readonly _changedTick: number[];
+    readonly accessorColumns: (AccessorColumns | undefined)[];
+    private readonly _fieldGid;
+    readonly columnIds: number[];
+    readonly changedTick: number[];
     private readonly _mutGroupCache;
     private readonly _readGroupCache;
     /** Host-installed grow hook. Set by `Store` on every SAB-backed
-     * archetype during construction; `null` on heap-backed archetypes (the
+     * archetype during construction. `null` on heap-backed archetypes (the
      * default `GrowableTypedArray` grows in place). Insertion methods call
      * `_invoke_grow(...)` below before any push that would overflow the
-     * current SAB row capacity. (#171 §6.1.9 Phase 3) */
+     * current SAB row capacity. */
     growHandler: ArchetypeGrowHandler | null;
     constructor(id: ArchetypeID, mask: BitSet, layouts?: ArchetypeColumnLayout[], initialCapacity?: number, columnFactory?: ColumnFactory);
+    /** Row `from` of `src` → row `to` here. `map[i]` is the source column of
+     * column `i`, or negative when the source has no such column. Such a column
+     * gets `0`. Both planes are width-canonical, and a shared column has one
+     * width on both sides, so the copy is a bit copy. */
+    private _copyRowFrom;
+    /** A row's ticks travel with the row across a transition, so a record made
+     * before the move still drains after it. A component the source lacks gets
+     * 0: the add is structural, and `onAdd` reports it. Cold: reached only when
+     * this archetype carries a tick plane. */
+    private _copyTicksFrom;
+    /** Give `cid` a row tick column, the row grain of an entity-level `onSet`.
+     * No-op for a component this archetype lacks, for a tag (no field, so no
+     * write to record), and when the column exists. Cold: registration of an
+     * observer, and the birth of an archetype while one is registered. */
+    installTicks(cid: number): void;
+    /** Forget every record. A restore replaces the rows under the plane, so a
+     * tick that survived it would name a write that never happened. */
+    resetTicks(): void;
+    /** Grow each tick column to `_rowCap` and place the plane after the data
+     * columns in `rowBufs`. Called by `_syncRowPlane`, after it settled the
+     * capacity, and only when a plane exists. */
+    private _syncTicks;
+    /** Row `from` → row `to`, every column. The swap-remove fill. */
+    private _moveRow;
+    /** Exchange rows `a` and `b`, every column. */
+    private _swapRow;
+    /** `0` into row `row`, every column. */
+    private _zeroRow;
+    /** `bits[i]` into row `row` of column `i`, every column, through the
+     * width-canonical plane. `bits` must come from `widthBits`, so each entry is
+     * already the column's stored representation and no conversion remains. The
+     * single-append primitive behind `spawn`. */
+    private _writeRowBits;
+    /** Re-derive the `bufs`, `_eids` and `_rowCap` row plane from the backing
+     * columns. The sole writer of all three, see the `bufs` field doc for the
+     * invariant it restores. Cold: construction, `refreshViews`, tail of a grow. */
+    private _syncRowPlane;
+    /** Re-point every cached `forEachChunk` column group at the current `bufs`.
+     *
+     * Called only from `_syncRowPlane`, which is the only thing that can change a
+     * column's buffer identity, so after this runs, a cached group is correct by
+     * construction, and `columnGroupMut` and `columnGroupRead` need no staleness test
+     * at all. That absence is the point: those two run once per archetype per
+     * `forEachChunk` pass, which for a fragmented query is once per chunk, and this
+     * file already carries one hard-won lesson (`_onArchShrink`): one more
+     * statement pushed that per-mutation function past V8's inlining budget, and
+     * it became much slower. We measured two earlier forms of this optimisation
+     * and rejected both for the same cause. A fill through a shared helper made
+     * fragmented iteration slower, and an inline test for a stale buffer also made
+     * it slower. Each loss was larger than the gain in system dispatch. Move the
+     * work to the cold path, and the gain stays with no loss.
+     *
+     * Refreshes in place, preserving object identity, for the same reason
+     * `_syncRowPlane` refills `bufs` in place: a caller that captured the group
+     * sees fresh buffers rather than silently stale ones. */
+    private _refreshColumnCaches;
+    /** DEV-only: assert the row plane still addresses the live buffers.
+     *
+     * `bufs` and `_eids` and `flatColumns[i].buf` and `_entityIds.buf` are two paths to
+     * one buffer, and only the first is cached, the row ops index the cache while
+     * `getColumnRead` and `writeFields` read `.buf` fresh. Anything that changes a
+     * buffer's identity owes a `_syncRowPlane`. Miss one and the two paths split
+     * silently, with row writes landing in an orphan that later reads never see.
+     *
+     * Checked at the boundaries that read `.buf` directly, and O(1): index 0 alone
+     * is enough, because `_syncRowPlane` rewrites every entry together. There is
+     * no way to desync one column and not the first. */
+    private _assertRowPlaneFresh;
+    /** Make room for `additional` more rows, growing if the append would
+     * overflow. Replaces the `this.length >= cols[0].buf.length` probe the append
+     * paths each open-coded, that read a column object and its buffer's length
+     * on every single-row append. This is one compare against a cached number.
+     *
+     * Every append path calls this, and the spawn path calls it first so it can
+     * reserve capacity before it commits an entity slot. A cap grow throws here,
+     * with the world untouched, instead of mid-append after the slot is live.
+     * See `Store.spawn` and `spawnMany`.
+     *
+     * Both backings are handled by `_growRows` so callers don't branch: a
+     * SAB-backed archetype delegates to the store's `growHandler` (realloc +
+     * republish, which re-enters `refreshViews`), a heap-backed one
+     * (`growHandler === null`, the unit-test factory) grows each column in place.
+     * Either way the buffers may have moved, so the row plane is re-synced before
+     * returning, including when the grow throws. */
+    reserveRows(additional: number): void;
+    /** Cold half of `reserveRows`: the append genuinely doesn't fit, so grow.
+     * Never called on the fast path, see the caller. */
+    private _growRows;
+    /** Push `Archetype.length` down into each column's own logical length (and
+     * the entity-id array's). The row plane keeps `length` authoritative and never
+     * touches `_len`, so the columns' view of it goes stale between publishes.
+     * Nothing on the ECS hot paths reads it. The boundaries that do, a
+     * reallocating `reserve`, `refreshView`'s shrink check, `view()`,
+     * publish first. */
+    private _publishRowCounts;
     /**
      * Build an Archetype whose columns are TypedArray views into a single
      * `ColumnStore`-managed `SharedArrayBuffer`. The store must contain an
      * archetype entry whose id equals `storeArchetypeId` and whose columns
      * cover every `(component_id, fieldIdx)` pair declared by `layouts`.
      *
-     * The resulting archetype is fixed-capacity at the SAB row capacity —
+     * The resulting archetype is fixed-capacity at the SAB row capacity,
      * any operation that would push past it throws `StoreColumnOverflowError`.
      * To grow capacity, call `growColumnStore(...)` between ticks and then
-     * `refreshViews(newStore)` on this archetype (#171 §6.1.4 / §8.1).
+     * `refreshViews(newStore)` on this archetype.
      */
     static fromColumnStore(id: ArchetypeID, mask: BitSet, layouts: ArchetypeColumnLayout[], columnStore: ColumnStore, storeArchetypeId: number): Archetype;
     /** True iff this archetype was constructed via `fromColumnStore` and its
-     * `_flatColumns` are SAB-backed. Heap-backed archetypes return `false`
+     * `flatColumns` are SAB-backed. Heap-backed archetypes return `false`
      * and cannot be refreshed (their columns grow in place). */
     get isBufferBacked(): boolean;
     /**
      * Repoint every column at the matching SAB view in `newColumnStore` after
      * a host-side `growColumnStore` realloc. The archetype keeps its row
-     * count; each column's logical length is preserved. Caller is responsible
+     * count. Each column's logical length is preserved. Caller is responsible
      * for ensuring `newColumnStore` was built by `growColumnStore` over the
-     * SAB this archetype was originally drawn from — the matching
+     * SAB this archetype was originally drawn from, the matching
      * `storeArchetypeId` was recorded in `fromColumnStore` and is reused here.
      *
      * Throws `ECSError` if this archetype is not SAB-backed, or if the new
@@ -228,42 +287,42 @@ export declare class Archetype implements ArchetypeView {
      * expects.
      */
     refreshViews(newColumnStore: ColumnStore): void;
-    /** Enabled-row count — the default iteration bound (#577). See `enabled_count`.
+    /** Enabled-row count, the default iteration bound. See `enabled_count`.
      * Equals `length` whenever no entity is disabled (the common case).
      *
      * During an `includeDisabled()` query's `forEach`, the module flag
-     * `_iterAllRows` is set so this returns `length` (enabled + disabled) — the
+     * `iterAllRows` is set so this returns `length` (enabled + disabled), the
      * user's `for i < arch.entityCount` loop then spans disabled rows
      * transparently, with no change to the loop. Outside such iteration the flag is
      * false and this is `enabled_count`. */
     get entityCount(): number;
-    /** Total live rows incl. disabled (#577). */
+    /** Total live rows incl. disabled. */
     get totalCount(): number;
-    /** Disabled-row count (#577). */
+    /** Disabled-row count. */
     get disabledCount(): number;
     /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
      * 0..totalCount-1 (enabled rows first, then disabled). */
     get entityIds(): ReadonlyEntityIDArray;
     /**
-     * Swap the two rows `a` and `b` — entity ids and every column. Does NOT touch
-     * `entityRow`; the caller updates the entity→row map for whichever rows it
+     * Swap the two rows `a` and `b`, entity ids and every column. Does not touch
+     * `entityRows`. The caller updates the entity→row map for whichever rows it
      * cares about (it knows the two `entityIds` after the swap). The partition
-     * primitives (`disableRow`/`enableRow`/`removeRow`/`_placeTail`) build on
+     * primitives (`disableRow`, `enableRow`, `removeRow` and `_placeTail`) build on
      * this. Writes through each column's live backing buffer (`buf`), so it works
-     * for both heap- and SAB-backed columns. No-op when `a === b`. (#577) */
+     * for both heap- and SAB-backed columns. No-op when `a === b`. */
     swapRows(a: number, b: number): void;
     /**
-     * Place a freshly-appended ENABLED entity (currently at the tail row `tail`,
+     * Place a freshly-appended enabled entity (currently at the tail row `tail`,
      * already pushed, `length` already incremented) into the enabled region, and
      * bump `enabled_count`. Returns its final row.
      *
-     * Common case — no disabled rows (`enabled_count === tail`): the tail row IS
-     * the next enabled slot, so this is just `enabled_count++` and returns `tail`
-     * (byte-for-byte the pre-#577 behaviour, `entityRow` untouched). Rare case —
+     * Common case, no disabled rows (`enabled_count === tail`): the tail row is
+     * the next enabled slot, so this is only `enabled_count++` and returns `tail`
+     * (byte-for-byte the earlier behaviour, `entityRows` untouched). Rare case,
      * disabled rows occupy `[enabled_count, tail)`: swap the appended row into the
      * first disabled slot and push that disabled occupant to the tail, updating
-     * its `entityRow`. Requires `entityRow` in that case (a `DEV` guard fires
-     * if a caller appends into a disabled-bearing archetype without passing it). (#577) */
+     * its `entityRows`. Requires `entityRows` in that case (a `DEV` guard fires
+     * if a caller appends into a disabled-bearing archetype without passing it). */
     private _placeTail;
     /**
      * Bulk analog of `_placeTail` for `count` freshly-appended enabled rows at
@@ -271,64 +330,66 @@ export declare class Archetype implements ArchetypeView {
      * start`): `enabled_count += count`, return `start`. The bulk callers
      * (`spawnMany`, batch ops) fall back to a per-entity append loop when the
      * target already has disabled rows, so the rare branch is a `DEV` guard
-     * rather than a block-rotation. (#577) */
+     * rather than a block-rotation. */
     private _placeTailBulk;
     /**
      * Disable the entity at `row` (precondition: enabled, `row < enabled_count`).
      * Swaps it to the end of the enabled region and shrinks the region, so it
-     * lands in the disabled tail with its data intact — no archetype transition,
-     * O(1)+one row swap. Updates `entityRow` for both rows touched. (#577) */
-    disableRow(row: number, entityRow: Int32Array): void;
+     * lands in the disabled tail with its data intact, no archetype transition,
+     * O(1)+one row swap. Updates `entityRows` for both rows touched. */
+    disableRow(row: number, entityRows: Int32Array): void;
     /**
      * Enable the entity at `row` (precondition: disabled, `row >= enabled_count`).
      * Swaps it to the front of the disabled region and grows the enabled region.
-     * Updates `entityRow` for both rows touched. (#577) */
-    enableRow(row: number, entityRow: Int32Array): void;
+     * Updates `entityRows` for both rows touched. */
+    enableRow(row: number, entityRows: Int32Array): void;
     /**
-     * Partition-aware swap-remove that owns its `entityRow` updates (#577). The
-     * Store's destroy/move paths call this instead of `removeEntity`; it keeps the
+     * Partition-aware swap-remove that owns its `entityRows` updates. The
+     * Store's destroy and move paths call this instead of `swapRemoveRow`. It keeps the
      * enabled prefix contiguous in every case:
      *  - disabled row (`row >= enabled_count`): swap-remove within the disabled
-     *    tail (the last row is disabled) — `enabled_count` unchanged.
-     *  - last enabled row: swap-remove with the global last; `enabled_count--`.
+     *    tail (the last row is disabled), `enabled_count` unchanged.
+     *  - last enabled row: swap-remove with the global last. `enabled_count--`.
      *  - middle enabled row: move the last enabled row into the hole (so the
      *    enabled prefix stays packed), then swap-remove that vacated enabled slot
-     *    with the global last; `enabled_count--`.
-     * Updates `entityRow` for every relocated entity (never for the removed one —
-     * the caller frees/repoints it). */
-    removeRow(row: number, entityRow: Int32Array): void;
-    /** @internal — cold partition-aware tail of `removeRow` (#577): the
+     *    with the global last. `enabled_count--`.
+     * Updates `entityRows` for every relocated entity (never for the removed one,
+     * the caller frees and repoints it). */
+    removeRow(row: number, entityRows: Int32Array): void;
+    /** @internal, cold partition-aware tail of `removeRow`: the
      * disabled-bearing archetype case. Split out so the no-disabled fast path
-     * above stays small enough to inline (#649); see the doc on `removeRow`. */
+     * above stays small enough to inline. See the doc on `removeRow`. */
     private _removeRowPartitioned;
-    get entityList(): Uint32Array;
+    /** The entity ids of the live rows, bounded by `length`. `entityIds` returns
+     * the same buffer at its full capacity, so a walk uses this one. */
+    get rowEntityIds(): Uint32Array;
     hasComponent(id: ComponentID): boolean;
     matches(required: BitSet): boolean;
     /**
-     * Get a single field's column (read-only — use when not mutating). Valid
+     * Get a single field's column (read-only, use when not mutating). Valid
      * data: indices 0..entityCount-1. The `ReadonlyColumn` return is an
      * *advisory* compile-time barrier: it is the live mutable backing buffer,
      * so the `readonly` index signature blocks writes at the type layer only
-     * (a §10c-policed cast can still write through). For writes use the
-     * mutable `getColumn` (tick-bumping) below.
+     * (a deliberate cast can still write through). For writes use the
+     * mutable `getColumnMut` (tick-bumping) below.
      */
     getColumnRead<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K): ReadonlyColumn;
     /**
-     * Tuple fetch of several of one component's columns —
+     * Tuple fetch of several of one component's columns,
      * `const [q, r] = arch.getColumnsRead(HexPos, "q", "r")` collapses the
      * per-field `getColumnRead` preamble at the top of an iteration callback
      * to one line. Same advisory-readonly views and `reads` access-check as
-     * `getColumnRead`. Allocates one small array per call — fine once per
-     * archetype per tick; in a per-row loop fetch columns individually.
+     * `getColumnRead`. Allocates one small array per call, fine once per
+     * archetype per tick. In a per-row loop fetch columns individually.
      */
     getColumnsRead<S extends ComponentSchema, const K extends readonly (string & keyof S)[]>(def: ComponentDef<S>, ...fields: K): {
         [I in keyof K]: ReadonlyColumn;
     };
     /**
      * Get a single field's column **if this archetype has the component**, else
-     * `undefined` — the fetch-if-present accessor for optional query terms (#575,
-     * Bevy `Option<&T>` / flecs `?`). An optional query (`q.optional(T)`) spans
-     * archetypes both with and without `T`; the caller branches once per
+     * `undefined`, the fetch-if-present accessor for optional query terms
+     * (Bevy `Option<&T>`, flecs `?`). An optional query (`q.optional(T)`) spans
+     * archetypes both with and without `T`. The caller branches once per
      * archetype span on the return:
      *
      *   q.forEach((arch) => {
@@ -342,23 +403,23 @@ export declare class Archetype implements ArchetypeView {
      * **absent** branch, not a thrown error. The `DEV` checks still run
      * **first** (before the absent short-circuit), so the requirements don't
      * depend on whether the current span happens to hold `T`. Two checks fire:
-     * (1) `accessCheck.checkRead` — an optional read needs `reads:[T]` coverage
-     * exactly as a required read does; (2) `accessCheck.checkOptionalFetch` —
-     * the iterating query must have declared `.optional(T)` (#592), the read-side
+     * (1) `accessCheck.assertRead`, an optional read needs `reads:[T]` coverage
+     * exactly as a required read does, and (2) `accessCheck.assertOptionalFetch`,
+     * the iterating query must have declared `.optional(T)`, the read-side
      * analog that makes the query term the fetch's authorization rather than inert
      * decoration. The return is the same advisory-readonly view `getColumnRead`
      * hands back.
      */
     getOptionalColumnRead<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K): ReadonlyColumn | undefined;
-    /** Get a single field's column (mutable — the default). Marks the component as changed at the given tick. */
-    getColumn<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K, tick: number): TagToTypedArray[S[K]];
-    /** Mutable field-keyed column group; stamps the change tick once. */
+    /** Get a single field's column (mutable, the default). Marks the component as changed at the given tick. */
+    getColumnMut<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K, tick: number): TagToTypedArray[S[K]];
+    /** Mutable field-keyed column group. Stamps the change tick once. */
     columnGroupMut<S extends ComponentSchema>(def: ComponentDef<S>, tick: number): MutableColumnsForSchema<S>;
     /** Read-only field-keyed column group (no tick bump). */
     columnGroupRead<S extends ComponentSchema>(def: ComponentDef<S>): ColumnsForSchema<S>;
     writeFields(row: number, componentId: ComponentID, values: Record<string, number>, tick: number): void;
     /**
-     * Bulk variant of `writeFields` — fills `count` consecutive rows starting
+     * Bulk variant of `writeFields`, fills `count` consecutive rows starting
      * at `dstStart` with the same field values via per-field `TypedArray.fill`.
      * For N rows of an F-field component, this is F native fill calls instead
      * of N×F per-row JS writes. The change-tick is bumped once for the range,
@@ -375,67 +436,74 @@ export declare class Archetype implements ArchetypeView {
      * Add an entity. Pushes zeroes into all columns and returns the assigned row.
      * Store is responsible for tracking entityIndex → row.
      */
-    addEntity(entityId: EntityID, entityRow?: Int32Array): number;
+    addEntity(entityId: EntityID, entityRows?: Int32Array): number;
     /**
      * Remove entity at row via swap-and-pop. Swaps the last entity into the
      * vacated row to keep data dense. Returns the entityIndex of the swapped
      * entity (so Store can update its row), or NO_SWAP if no swap was needed.
      */
-    removeEntity(row: number): number;
+    swapRemoveRow(row: number): number;
     /** Tag-optimized add: skip column push entirely (no data to store). */
-    addEntityTag(entityId: EntityID, entityRow?: Int32Array): number;
+    addEntityTag(entityId: EntityID, entityRows?: Int32Array): number;
     /**
      * Bulk add `count` entities, zero-initialising all columns. Returns the
      * starting dstRow for the batch. Caller is responsible for tracking
      * entityIndex → row for every entity in the batch.
      *
-     * Collapses the N×C `push(0)` cost of N sequential `addEntity` calls
-     * into C `bulkAppendZeroes(count)` calls — the same pattern
-     * `bulkMoveAllFrom` (`:580`) uses for the move-with-data case (#330).
+     * Collapses the N×C per-element cost of N sequential `addEntity` calls into
+     * C `fill` calls, one for each column, the same pattern `bulkMoveAllFrom`
+     * uses for the move-with-data case.
      */
     addEntities(entityIds: Uint32Array, count?: number): number;
     /** Tag-optimized bulk add: skip the per-column zero-fill entirely. */
     addEntitiesTag(entityIds: Uint32Array, count?: number): number;
-    /** Grow column capacity to fit `additional` more rows if the next append
-     * would overflow — the exact grow trigger the `addEntityWithValues` /
-     * `addEntitiesWithValues` appends run internally, lifted out so the spawn
-     * path can pre-reserve capacity BEFORE it commits an entity slot. A SAB-cap
-     * grow throws here (with the world untouched) instead of mid-append after the
-     * slot is already live — see `Store.spawn`/`spawnMany` (#775). No-op for a
-     * tag-only archetype (no SAB columns) or when no grow handler is installed. */
-    ensureRowCapacity(additional: number): void;
-    /** Append one entity, writing `flatValues[i]` straight into column `i`
-     * (in `_flatColumns` order) — no zero-fill-then-overwrite. Bumps every
-     * column's change tick once. Returns the assigned row. */
-    addEntityWithValues(entityId: EntityID, flatValues: number[], tick: number, entityRow?: Int32Array): number;
+    /** Append one entity, writing `flatBits[i]` straight into column `i` (in
+     * `flatColumns` order), no zero-fill-then-overwrite. Bumps every column's
+     * change tick once. Returns the assigned row. `flatBits` must come from
+     * `widthBits`: each entry is already the column's stored representation, so
+     * the write is a bit copy through the width-canonical plane, with no
+     * conversion and no call for each column type. A template resolves its
+     * defaults into bits one time, so every `spawn` from it takes this path. */
+    addEntityWithBits(entityId: EntityID, flatBits: Float64Array, tick: number, entityRows?: Int32Array): number;
+    /** Convert `flatValues` (in `flatColumns` order) to the stored bit
+     * pattern of each column, as the width-canonical view represents it
+     * (`toWidthBits`). The result is what `addEntityWithBits` writes. A
+     * `Float64Array`, so the append reads each entry with no hole test and no
+     * unboxing. Every bit pattern is an integer below 2^32 or an `f64`, and
+     * both are exact in it. */
+    widthBits(flatValues: number[]): Float64Array;
+    /** Write one value into row `row` of flat column `idx`, converting as the
+     * column's type converts, through the access site of that type. The
+     * per-instance override path of `spawn`. */
+    writeFlatElem(idx: number, row: number, value: number): void;
     /** Bulk append `count` entities, filling column `i` with `flatValues[i]`
      * in a single `TypedArray.fill` per column (no zero pass). Returns the
      * starting row. */
     addEntitiesWithValues(entityIds: Uint32Array, count: number, flatValues: number[], tick: number): number;
-    /** Tag-optimized remove via swap-and-pop: skip column swap/pop entirely. */
-    removeEntityTag(row: number): number;
+    /** Tag-optimized remove via swap-and-pop: skip column swap and pop entirely. */
+    swapRemoveRowTag(row: number): number;
     /**
      * Move an entity from src archetype into this archetype in a single pass.
-     * Combines addEntity + copySharedFrom + removeEntity(src).
+     * Combines addEntity + copySharedFrom + swapRemoveRow(src).
      * Uses a pre-computed transition map for branchless column copy.
      * Writes dstRow to _moveResult[0], swapped entity index to _moveResult[1].
      */
-    moveEntityFrom(src: Archetype, srcRow: number, entityId: EntityID, transitionMap: Int16Array, tick: number, entityRow: Int32Array): void;
+    moveEntityFrom(src: Archetype, srcRow: number, entityId: EntityID, transitionMap: Int16Array, tick: number, entityRows: Int32Array): void;
     /**
      * Move an entity from src into this archetype (tag-only: no columns to copy).
-     * Writes dstRow to _moveResult[0]; _moveResult[1] is always NO_SWAP (the
-     * partition-aware src/dst updates are owned internally, #577).
+     * Writes dstRow to _moveResult[0]. _moveResult[1] is always NO_SWAP (the
+     * partition-aware src/dst updates are owned internally).
      */
-    moveEntityFromTag(src: Archetype, srcRow: number, entityId: EntityID, entityRow: Int32Array): void;
+    moveEntityFromTag(src: Archetype, srcRow: number, entityId: EntityID, entityRows: Int32Array): void;
     /**
-     * Bulk-move ALL entities from src into this archetype using TypedArray.set().
+     * Bulk-move all entities from src into this archetype using TypedArray.set().
      * Much faster than per-entity moveEntityFrom when the entire source is moving.
      * After this call, src is empty. Returns the starting dstRow for the batch.
      */
     bulkMoveAllFrom(src: Archetype, transitionMap: Int16Array, tick: number): number;
     /**
-     * Drop every row at once — length → 0, entity-id list and all columns
-     * cleared — without copying into a destination. Used when an archetype's
+     * Drop every row at once, length → 0, entity-id list and all columns
+     * cleared, without copying into a destination. Used when an archetype's
      * entire population leaves in one move: `bulkMoveAllFrom` clears the
      * source this way, and `Store.batchRemoveComponent` calls it directly when
      * the destination is the rowless empty archetype (batch-removing the last
@@ -444,16 +512,16 @@ export declare class Archetype implements ArchetypeView {
     clearRows(): void;
     /**
      * Re-derive the host-side row bookkeeping after a snapshot is mounted onto a
-     * live world (#789, `Store.restoreInto`). A snapshot reloads the column bytes
-     * (dense SAB) but NOT the host-side `length` / `enabledCount` / `_entityIds`
-     * back-reference — those are reconstructed here. `refreshViews` must have
+     * live world (`Store.restore`). A snapshot reloads the column bytes
+     * (dense SAB) but not the host-side `length`, `enabledCount` and `_entityIds`
+     * back-reference, those are reconstructed here. `refreshViews` must have
      * already repointed the columns at the restored SAB.
      *
      * The caller scans the restored entity-index region to learn which entity
      * occupies each row and passes them in row order (`rowEntityIds[r]` is the
-     * packed `EntityID` at row `r`; rows `[0, length)` are dense, enabled rows
-     * first then disabled per the #577 partition). `enabledCount` is the restored
-     * partition boundary. This is the inverse of the per-row `addEntity` /
+     * packed `EntityID` at row `r`. Rows `[0, length)` are dense, enabled rows
+     * first then disabled per the partition). `enabledCount` is the restored
+     * partition boundary. This is the inverse of the per-row `addEntity` and
      * `disableRow` bookkeeping the live run accumulated.
      */
     restoreHostRows(rowEntityIds: readonly number[], enabledCount: number): void;
@@ -461,19 +529,20 @@ export declare class Archetype implements ArchetypeView {
     setEdge(componentId: ComponentID, edge: ArchetypeEdge): void;
     /**
      * Get the transition map from this archetype to `target`, building and caching
-     * it on miss. Used by Store.addComponents / removeComponents — the per-edge
-     * cache only covers single-component steps.
+     * it on miss. `Store.addComponents` and `Store.removeComponents` use it. The
+     * per-edge cache only covers single-component steps.
      */
-    getBatchTransitionMap(target: Archetype): Int16Array;
-    /** Look up a cached plural-add transition by its packed key (#659). Returns
+    transitionMapTo(target: Archetype): Int16Array;
+    /** Look up a cached plural-add transition by its packed key. Returns
      * `undefined` until the first composite add out of this archetype plants the
-     * lazy Map — the common case for archetypes that only ever see single adds. */
+     * lazy Map, the common case for archetypes that only ever see single adds. */
     getCompositeAddEdge(key: number): CompositeAddEdge | undefined;
     /** Cache a resolved plural-add transition (target + src→target map) under its
-     * packed key (#659), allocating the backing Map on first use. */
+     * packed key, allocating the backing Map on first use. */
     cacheCompositeAddEdge(key: number, target: ArchetypeID, map: Int16Array): void;
 }
-/** Reusable result buffer for move_entity_from/move_entity_from_tag. [dstRow, swapped_index] */
+/** Reusable result buffer for `moveEntityFrom` and `moveEntityFromTag`.
+ * `[dstRow, swappedIndex]`. */
 export declare const _moveResult: [number, number];
 export declare function _setIterAllRows(value: boolean): boolean;
 /**
@@ -481,6 +550,5 @@ export declare function _setIterAllRows(value: boolean): boolean;
  * For each column in dst, stores the index of the corresponding column in src,
  * or -1 if the column is new (no source).
  */
-export declare function buildTransitionMap(src: Archetype, dst: Archetype): Int16Array;
-export {};
+export declare function createTransitionMap(src: Archetype, dst: Archetype): Int16Array;
 //# sourceMappingURL=archetype.d.ts.map