@oasys/oecs 0.3.0 → 0.4.0

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

@@ -0,0 +1,77 @@
+import { ComponentDef, ComponentHandle } from './component';
+import { SparseComponentDef } from './sparse_store';
+import { RelationDef } from './relation';
+import { ResourceKey } from './resource';
+import { SystemDescriptor } from './system';
+interface AccessSets {
+    reads: Set<number>;
+    writes: Set<number>;
+    addAllowed: Set<number>;
+    removeAllowed: Set<number>;
+    hasDespawns: boolean;
+    resourceReads: Set<symbol>;
+    resourceWrites: Set<symbol>;
+    sparseReads: Set<number>;
+    sparseWrites: Set<number>;
+    relationReads: Set<number>;
+    relationWrites: Set<number>;
+}
+declare function setsFor(desc: SystemDescriptor): AccessSets;
+/** The reads-only access surface a run condition declares (#576). A condition
+ * can only `reads` components (via a captured query) and `resourceReads`; every
+ * mutation set is empty by construction, so the same `check_*` machinery rejects
+ * any write/structural/resource-write a misbehaving predicate attempts. */
+interface ConditionAccess {
+    readonly name: string;
+    readonly reads?: readonly ComponentDef[];
+    readonly resourceReads?: readonly ResourceKey<unknown>[];
+}
+declare class AccessCheck {
+    private active;
+    private sets;
+    private activeName;
+    private exclusive;
+    enter(desc: SystemDescriptor): void;
+    /** Open a reads-only span for a run condition (#576). No descriptor — a
+     * condition can gate a whole SystemSet, so it isn't attributable to one
+     * system — just its declared reads/resource_reads and a name for diagnostics.
+     * Paired with `leave()`. */
+    enterCondition(cond: ConditionAccess): void;
+    leave(): void;
+    isActive(): boolean;
+    /** Current system descriptor, if any. Null during a run-condition span. */
+    current(): SystemDescriptor | null;
+    checkRead(def: ComponentHandle): void;
+    checkWrite(def: ComponentHandle): void;
+    checkAdd(def: ComponentHandle): void;
+    checkRemove(def: ComponentHandle): void;
+    checkDestroy(): void;
+    checkResourceRead(key: ResourceKey<unknown>): void;
+    checkResourceWrite(key: ResourceKey<unknown>): void;
+    checkSparseRead(def: SparseComponentDef): void;
+    checkSparseWrite(def: SparseComponentDef): void;
+    checkRelationRead(def: RelationDef): void;
+    checkRelationWrite(def: RelationDef): void;
+    /** A `(*, T)` wildcard (`Query.forEachRelatedTo`, #579) reads every
+     * relation's reverse index, so it can't name a specific relation — it is
+     * authorised by the `ANY_RELATION` sentinel in `relationReads`. Honoured here
+     * exactly like a per-relation read, just keyed on the reserved sentinel id
+     * (which computeSets folds into `relationReads` like any other entry). */
+    checkRelationReadAny(): void;
+    private optionalScopes;
+    enterOptionalScope(optional: readonly number[]): void;
+    leaveOptionalScope(): void;
+    checkOptionalFetch(def: ComponentHandle): void;
+    private failComponent;
+    private failSparse;
+    private failRelation;
+    private failResource;
+}
+export declare const accessCheck: AccessCheck;
+/** @internal — test seam for unit tests that need a fresh tracker. */
+export declare const _accessCheckInternals: {
+    create: () => AccessCheck;
+    setsFor: typeof setsFor;
+};
+export {};
+//# sourceMappingURL=access_check.d.ts.map

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

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

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

@@ -0,0 +1,474 @@
+import { Brand, AnyTypedArray, ColumnBacking, TypedArrayTag, BitSet } from '../../type_primitives';
+import { ColumnStore } from '../store/column_store';
+import { ComponentID, ComponentDef, ComponentSchema, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn } from './component';
+import { EntityID, ReadonlyEntityIdArray } from './entity';
+export type ArchetypeID = Brand<number, "archetype_id">;
+export declare const asArchetypeId: (value: number) => ArchetypeID;
+export interface ArchetypeEdge {
+    add: ArchetypeID | null;
+    remove: ArchetypeID | null;
+    /** Pre-computed column mapping for add direction: this → add target. */
+    addMap: Int16Array | null;
+    /** Pre-computed column mapping for remove direction: this → remove target. */
+    removeMap: Int16Array | null;
+}
+/**
+ * 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).
+ *
+ * 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
+ * the final-mask resolve repeats every call into one `Map.get`. Never
+ * invalidated: the archetype graph is monotonic (archetypes outlive the Store).
+ */
+export interface CompositeAddEdge {
+    target: ArchetypeID;
+    map: Int16Array;
+}
+export interface ArchetypeColumnLayout {
+    componentId: ComponentID;
+    fieldNames: string[];
+    fieldIndex: Record<string, number>;
+    fieldTypes: TypedArrayTag[];
+}
+interface ArchetypeColumnGroup {
+    layout: ArchetypeColumnLayout;
+    columns: ColumnBacking<AnyTypedArray>[];
+}
+/**
+ * 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.
+ */
+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
+ * 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)
+ */
+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 {
+    /** 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. */
+    getColumnRead<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, 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<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 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;
+    readonly hasColumns: boolean;
+    /**
+     * 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
+     * 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
+     * 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
+     * `[0, enabled_count)` are enabled, `[enabled_count, length)` are disabled.
+     * `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.
+     */
+    enabledCount: number;
+    /**
+     * Flush-epoch stamp + captured pre-counts for the Store's per-entity flush
+     * 0-crossing detector (#328, #812): `_flushAdds`/`_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
+     * `stateHash`/snapshot.
+     */
+    _flushSeenEpoch: number;
+    _flushPreLen: number;
+    _flushPreEnabled: 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 —
+     * archetypes live for the Store's lifetime.
+     */
+    private readonly batchTransitionMaps;
+    /**
+     * Per-set add-edge cache for `Store.addComponents` (#659), 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.
+     */
+    private compositeAddEdges;
+    readonly _flatColumns: ColumnBacking<AnyTypedArray>[];
+    /** 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
+     * isn't supported). */
+    private _storeArchetypeId;
+    readonly _colOffset: number[];
+    readonly _fieldCount: number[];
+    private readonly _fieldIndex;
+    private readonly _fieldNames;
+    readonly columnGroups: (ArchetypeColumnGroup | undefined)[];
+    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
+     * 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) */
+    growHandler: ArchetypeGrowHandler | null;
+    constructor(id: ArchetypeID, mask: BitSet, layouts?: ArchetypeColumnLayout[], initialCapacity?: number, columnFactory?: ColumnFactory);
+    /**
+     * 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 —
+     * 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).
+     */
+    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`
+     * 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
+     * for ensuring `newColumnStore` was built by `growColumnStore` over the
+     * 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
+     * store lacks the recorded archetype id or any column the archetype
+     * expects.
+     */
+    refreshViews(newColumnStore: ColumnStore): void;
+    /** Enabled-row count — the default iteration bound (#577). 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
+     * 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). */
+    get totalCount(): number;
+    /** Disabled-row count (#577). */
+    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
+     * cares about (it knows the two `entityIds` after the swap). The partition
+     * primitives (`disableRow`/`enableRow`/`removeRow`/`_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) */
+    swapRows(a: number, b: number): void;
+    /**
+     * 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 —
+     * 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) */
+    private _placeTail;
+    /**
+     * Bulk analog of `_placeTail` for `count` freshly-appended enabled rows at
+     * `[start, start+count)`. Common case (no disabled rows, `enabled_count ===
+     * 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) */
+    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;
+    /**
+     * 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;
+    /**
+     * Partition-aware swap-remove that owns its `entityRow` updates (#577). The
+     * Store's destroy/move paths call this instead of `removeEntity`; 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--`.
+     *  - 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
+     * disabled-bearing archetype case. Split out so the no-disabled fast path
+     * above stays small enough to inline (#649); see the doc on `removeRow`. */
+    private _removeRowPartitioned;
+    get entityList(): Uint32Array;
+    hasComponent(id: ComponentID): boolean;
+    matches(required: BitSet): boolean;
+    /**
+     * 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.
+     */
+    getColumnRead<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K): ReadonlyColumn;
+    /**
+     * 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.
+     */
+    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
+     * archetype span on the return:
+     *
+     *   q.forEach((arch) => {
+     *     const vx = arch.getOptionalColumnRead(Vel, "vx");
+     *     for (let i = 0; i < arch.entityCount; i++) {
+     *       px[i] += vx ? vx[i] : 0;   // absent span ⇒ vx === undefined
+     *     }
+     *   });
+     *
+     * Unlike `getColumnRead`, a component the archetype lacks is the expected
+     * **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
+     * 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. */
+    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
+     * 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,
+     * not once per row. Used by `Store.batchAddComponent` after a bulk move,
+     * where every freshly-added row shares the same field values.
+     */
+    bulkWriteFields(dstStart: number, count: number, componentId: ComponentID, values: Record<string, number>, tick: number): void;
+    /** Fast positional write: values[i] → field[i] in declaration order. No string lookup. */
+    writeFieldsPositional(row: number, componentId: ComponentID, values: ArrayLike<number>, tick: number): void;
+    readField(row: number, componentId: ComponentID, field: string): number;
+    /** Copy all shared component columns from source archetype at srcRow into dstRow. */
+    copySharedFrom(source: Archetype, srcRow: number, dstRow: number, tick: number): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Tag-optimized add: skip column push entirely (no data to store). */
+    addEntityTag(entityId: EntityID, entityRow?: 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).
+     */
+    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;
+    /** 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;
+    /**
+     * Move an entity from src archetype into this archetype in a single pass.
+     * Combines addEntity + copySharedFrom + removeEntity(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;
+    /**
+     * 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).
+     */
+    moveEntityFromTag(src: Archetype, srcRow: number, entityId: EntityID, entityRow: Int32Array): void;
+    /**
+     * 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
+     * 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
+     * component), where there is nothing to copy into.
+     */
+    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
+     * 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` /
+     * `disableRow` bookkeeping the live run accumulated.
+     */
+    restoreHostRows(rowEntityIds: readonly number[], enabledCount: number): void;
+    getEdge(componentId: ComponentID): ArchetypeEdge | undefined;
+    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.
+     */
+    getBatchTransitionMap(target: Archetype): Int16Array;
+    /** Look up a cached plural-add transition by its packed key (#659). 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. */
+    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. */
+    cacheCompositeAddEdge(key: number, target: ArchetypeID, map: Int16Array): void;
+}
+/** Reusable result buffer for move_entity_from/move_entity_from_tag. [dstRow, swapped_index] */
+export declare const _moveResult: [number, number];
+export declare function _setIterAllRows(value: boolean): boolean;
+/**
+ * Build a transition map from src archetype to dst archetype.
+ * 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 {};
+//# sourceMappingURL=archetype.d.ts.map

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

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

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

@@ -0,0 +1,43 @@
+import { ECS } from './ecs';
+import { OnDeleteTarget, RelationDef } from './relation';
+/** Options for a built-in relation. `exclusive` / `multi` are fixed (always
+ * exclusive — required for the chain/tree traversal helpers), so only the
+ * target-deletion cleanup policy is tunable. */
+export interface BuiltinRelationOptions {
+    /** What happens to a relation's sources when a target is destroyed.
+     * Defaults per relation (see each registrar). */
+    readonly onDeleteTarget?: OnDeleteTarget;
+}
+/**
+ * Register an **`IsA(instance → exemplar)`** relation — a thin instance-of link.
+ *
+ * - "all instances of exemplar E" is `world.sourcesOf(IsA, E)`.
+ * - the IsA chain (`instance → exemplar → …`) is walked with
+ *   `world.ancestorsOf(instance, IsA)` / `rootOf` / `cascadeOf(exemplar, IsA)`.
+ * - **No component inheritance** — IsA records the link only; materialization of
+ *   an instance from its exemplar stays a spawn-time copy (the template path,
+ *   #462), deliberately decoupled (#477 / #478). An exemplar is a real entity,
+ *   not a `Template` (a non-entity template can't be a relation target).
+ *
+ * Default `onDeleteTarget: "clear"` — destroying an exemplar drops its
+ * instances' IsA link but leaves the instances alive (the thin analog of
+ * flecs's `IsA`-remove, since there is no inherited data to strip). Pass
+ * `"delete"` for strong instance-of (exemplar death cascade-destroys instances).
+ */
+export declare function registerIsA(world: ECS, opts?: BuiltinRelationOptions): RelationDef;
+/**
+ * Register a **`ChildOf(child → parent)`** relation — a thin hierarchy link.
+ *
+ * - a parent's children are `world.sourcesOf(ChildOf, parent)`.
+ * - the hierarchy is walked with `world.ancestorsOf(child, ChildOf)` (up to the
+ *   root), `rootOf`, and `cascadeOf(root, ChildOf)` (down, breadth-first,
+ *   parents before children).
+ * - unlike flecs's `ChildOf`, this does **not** scope names/lookup — the engine
+ *   has no name registry; it is purely the structural parent link.
+ *
+ * Default `onDeleteTarget: "delete"` — destroying a parent cascade-destroys
+ * its whole subtree (flecs's default). Pass `"clear"` to let children survive as
+ * roots, or `"orphan"` to leave a dangling `targetOf`.
+ */
+export declare function registerChildOf(world: ECS, opts?: BuiltinRelationOptions): RelationDef;
+//# sourceMappingURL=builtin_relations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builtin_relations.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/builtin_relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;KAsBK;AAEL,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;gDAEgD;AAChD,MAAM,WAAW,sBAAsB;IACtC;qDACiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAKlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAKtF"}