@oasys/oecs 0.4.0 → 0.5.0

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

@@ -1,14 +1,36 @@
-import { EntityID } from './entity';
-import { FrameTraceSink } from './frame_trace';
-import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component';
-import { SparseComponentDef, SparseComponentID } from './sparse_store';
-import { RelationDef, RelationOptions } from './relation';
-import { EmptyEventSchema, EventDef, EventReader, EventSchema } from './event';
-import { BitSet, TypedArrayTag } from '../../type_primitives';
-import { Archetype, ArchetypeID } from './archetype';
-import { Query } from './query';
-import { InPlaceBufferAllocator, ColumnStoreRegionHandle, StoreRegionSpec, ColumnStore } from '../store';
-import { ECSMemoryCapContext } from './ecs_memory';
+import { EntityID } from './entity.js';
+import { FrameTraceSink } from './frame_trace.js';
+import { ComponentDef, ComponentHandle, ComponentSchema, FieldValues } from './component.js';
+import { SparseComponentDef, SparseComponentID } from './sparse_store.js';
+import { RelationDef, RelationOptions } from './relation.js';
+import { EmptyEventSchema, EventDef, EventReader, EventShape } from './event.js';
+import { BitSet, TypedArrayTag } from '../../type_primitives/index.js';
+import { Archetype, ArchetypeID } from './archetype.js';
+import { Query, QueryHost } from './query.js';
+import { ObserverHost } from './observer.js';
+import { InPlaceBufferAllocator, ColumnStoreRegionHandle, StoreRegionSpec, ColumnStore } from '../store/index.js';
+import { ECSMemoryCapContext } from './ecs_memory.js';
+export interface ComponentMeta {
+    /** Optional debug name from `registerComponent(schema, { name })` —
+     * diagnostic messages only, never behaviour. */
+    name?: string;
+    fieldNames: string[];
+    fieldIndex: Record<string, number>;
+    fieldTypes: TypedArrayTag[];
+    /** Has an onAdd observer — collect effective adds for this component. */
+    obsAdd: boolean;
+    /** Has an onRemove observer — collect effective removes for this component. */
+    obsRem: boolean;
+    /** Has an onDisable observer (#677) — collect effective disables for this
+     * component at the toggle drain. */
+    obsDisable: boolean;
+    /** Has an onEnable observer (#677) — collect effective enables for this
+     * component at the toggle drain. */
+    obsEnable: boolean;
+    /** Has a per-entity onSet observer — record dirty rows on the write path
+     * (the ADR-0012 opt-in dirty list). */
+    trackDirty: boolean;
+}
 /**
  * Effective `(component, entity)` structural events for one fixed-point round,
  * collected during `_flushAdds` / `_flushRemoves` and handed to the observer
@@ -38,8 +60,14 @@ export interface StructuralObserverEvents {
 type SchemaOf<D extends ComponentDef> = D extends ComponentDef<infer S> ? S : ComponentSchema;
 /** One typed template entry: `values` is checked against the def's schema —
  * a misspelled field is a compile error. Fields may be omitted (they default
- * to 0), so the map is `Partial`. */
-export type TemplateEntry<D extends ComponentDef = ComponentDef> = {
+ * to 0), so the map is `Partial`. Tag defs refuse `values` entirely — their
+ * `FieldValues` would otherwise degenerate to `Record<string, number>` (same
+ * pitfall as `ValuesArg`); a schema-erased `ComponentDef` falls into the
+ * valued branch, so untyped call sites keep the loose shape. */
+export type TemplateEntry<D extends ComponentDef = ComponentDef> = SchemaOf<D> extends Record<string, never> ? {
+    readonly def: D;
+    readonly values?: undefined;
+} : {
     readonly def: D;
     readonly values?: Partial<FieldValues<SchemaOf<D>>>;
 };
@@ -55,7 +83,7 @@ export type TemplateEntries<Defs extends readonly ComponentDef[]> = readonly [
 type TemplateFieldNames<Defs extends readonly ComponentDef[]> = Defs[number] extends ComponentDef<infer S> ? keyof S & string : never;
 /** Flat per-instance override map for `ECS.spawn`: any field of any
  * component in the template, each optional. A misspelled field is a compile
- * error (and still a `__DEV__` throw at runtime for untyped call sites). */
+ * error (and still a `DEV` throw at runtime for untyped call sites). */
 export type TemplateOverrides<Defs extends readonly ComponentDef[]> = {
     readonly [K in TemplateFieldNames<Defs>]?: number;
 };
@@ -132,39 +160,26 @@ export interface StoreOptions {
      * called per tick. */
     deterministic?: boolean;
 }
-export declare class Store {
-    private entityGenerations;
-    private entityHighWater;
-    private readonly entityFreeIndices;
-    private entityAliveCount;
+export declare class Store implements ObserverHost, QueryHost {
+    private readonly entityAllocator;
     private readonly componentMetas;
     private componentCount;
     private readonly sparseStores;
-    private readonly relations;
-    private _hasTargetCleanup;
-    private readonly eventChannels;
-    private readonly dirtyEventChannels;
-    private eventCount;
-    private readonly archetypes;
-    private readonly archetypeMap;
-    private nextArchetypeId;
-    private readonly componentIndex;
+    /** Debug names parallel to `sparseStores` — diagnostics only. */
+    private readonly sparseNames;
+    private readonly relationService;
+    private readonly events;
+    private readonly archGraph;
     private readonly registeredQueries;
     private emptyArchetypeId;
     private entityArchetype;
     private entityRow;
-    private readonly pendingDestroy;
-    private readonly pendingAddIds;
-    private readonly pendingAddDefs;
-    private readonly pendingAddValues;
-    private readonly pendingRemoveIds;
-    private readonly pendingRemoveDefs;
-    private readonly pendingToggleIds;
-    private readonly pendingToggleDisable;
+    private readonly _deferred;
+    private readonly _snapshots;
     _tick: number;
     /** Per-world frame-trace sink (ADR-0030), installed via `ECS.setTrace`.
      * `null` unless a consumer attaches a recorder. Every call site is
-     * `if (__DEV__) store._trace?.…`, so production builds dead-code-eliminate
+     * `if (DEV) store._trace?.…`, so production builds dead-code-eliminate
      * the seam and pay only this one nullable field. The sink observes; it never
      * folds into `stateHash` (a scheduling artifact, like `_changedTick` / the
      * observer state below). */
@@ -176,15 +191,14 @@ export declare class Store {
     private _toggleObserverCount;
     /** Reused effective-event scratch for the current flush round. */
     private readonly _obsEvents;
-    /** Installed by `ECS` — dispatches a round's collected events to the observer
-     * registry (ordering + callbacks), which may enqueue further structural ops. */
-    _structuralObserverHook: ((ev: StructuralObserverEvents) => void) | null;
-    /** Re-entrancy guard for the observed fixed-point loop. An observer callback
-     * must enqueue (add/remove) and let the loop settle it — calling `ctx.flush()`
-     * from inside a callback would re-enter `flushStructural` and corrupt the
-     * shared event scratch. The guard turns that nested call into a no-op; the
-     * outer loop drains whatever the callback queued. */
-    private _flushingStructural;
+    /** Installed via `setStructuralObserverHook` — dispatches a round's collected
+     * events to the observer registry (ordering + callbacks), which may enqueue
+     * further structural ops. */
+    private _structuralObserverHook;
+    /** Install the structural-observer dispatch hook (called once by `ECS`
+     * during construction) — the named seam replacing direct writes to the
+     * previously-public field (M1). */
+    setStructuralObserverHook(fn: (ev: StructuralObserverEvents) => void): void;
     private _collectDestroyEid;
     private readonly _collectDestroyRemoveBit;
     private _collectToggleEid;
@@ -210,7 +224,7 @@ export declare class Store {
     /** Monotonic counter bumped by every membership-changing path (immediate
      * `addComponent(s)`, `removeComponent(s)`, `destroyEntity`,
      * `batchAddComponent`, `batchRemoveComponent`, `flushStructural`,
-     * `flushDestroyed`, and new-archetype installs in `archInstall`).
+     * `flushDestroyed`, and new-archetype installs in `ArchetypeGraph.install`).
      * Read by `Query._nonEmpty()` via `QueryResolver._getQueryDirtyEpoch`
      * — a query whose stored `_lastSeenEpoch` matches the current epoch
      * reuses its cached non-empty list (#327). Replaces the previous walk
@@ -221,17 +235,7 @@ export declare class Store {
     _queryDirtyEpoch: number;
     private readonly initialCapacity;
     private readonly _scratchTargetMask;
-    private readonly _hierarchyRadixOut;
-    private readonly _hierarchyRadixC0;
-    private readonly _hierarchyRadixC1;
     private _columnStore;
-    /** Single-slot Uint32Array view over the entity-index region's `length`
-     * header field. `createEntity`'s hot path writes `entityHighWater`
-     * here on every high-water bump; using a pre-built typed-array view
-     * skips the DataView lookup + setUint32 dispatch that #368 traced to
-     * ~25 ns/op on `frame_loop_focused: createEntity` (closes the
-     * post-#361 gap to oecs entirely). Rebuilt on SAB resize. */
-    private _entityIndexLengthView;
     /** Installed on every SAB-backed Archetype so the Archetype can
      * request a SAB grow when an insertion would exceed its column
      * capacity. Doubles the offending archetype's row capacity (or jumps
@@ -282,7 +286,7 @@ export declare class Store {
     /** Guard the canonical-ordering determinism surface. Throws
      * `DETERMINISM_DISABLED` when determinism wasn't opted into, naming the
      * method so the caller knows to pass `{ deterministic: true }`. Always on
-     * (not `__DEV__`-gated): the surface is cold (never per-tick) so one boolean
+     * (not `DEV`-gated): the surface is cold (never per-tick) so one boolean
      * check is free, and a silent non-canonical digest is the failure mode we're
      * preventing. */
     private _requireDeterministic;
@@ -338,7 +342,7 @@ export declare class Store {
      *
      * Lockstep walk: SAB descriptors are written by `extendColumnStore` in
      * the order non-SAB archetypes are promoted, which is the same id-order
-     * those archetypes occupy in `this.archetypes`. Iterating that array
+     * those archetypes occupy in `this.archGraph.archetypes`. Iterating that array
      * once, skipping non-SAB entries, and advancing an `archAddr` cursor
      * by the descriptor's `column_count` lets us write `row_count` without
      * the throwaway `Map<archId, length>` the previous version allocated
@@ -409,72 +413,42 @@ export declare class Store {
      * happened mid-tick), both of which are bugs the parity test would
      * surface. */
     entityIdAtRow(archetypeId: number, row: number): EntityID;
-    /**
-     * Find or create an archetype for the given component mask.
-     * Also updates the componentIndex and pushes into matching registered queries.
-     *
-     * Hot single-mask path. The bulk batched variant — used by Phase C
-     * pre-warming at `world.startup()` — is `archCreateManyFromMasks`;
-     * see #213 / `ECS.startup()` for how it gets called and why.
-     */
+    /** Find or create an archetype for the given component mask — see
+     * `ArchetypeGraph.getOrCreateFromMask`. */
     private archGetOrCreateFromMask;
-    /**
-     * Bulk variant of `archGetOrCreateFromMask` — Phase C of issue #213.
-     *
-     * Given a set of masks, creates Archetypes for the ones not already
-     * planted, in a SINGLE `extendColumnStore` call (instead of one per
-     * archetype). Single-mask creation is O(N) in archetypes-so-far because
-     * the extend has to copy every existing archetype's live rows forward;
-     * N such calls compound to O(N²). Batching collapses the per-archetype
-     * setup-and-copy down to one pass — the per-startup cost the design doc
-     * §5.2 calls out as "O(N²) → O(N)" for in-tree systems whose archetype
-     * set is known at registration time via `spawns` + `transitions`.
-     *
-     * Masks already in the map are skipped. Returns the resolved
-     * `ArchetypeID` per input mask in input order — callers that don't need
-     * the ids can ignore the return value.
-     */
+    /** Bulk variant of `archGetOrCreateFromMask` — one `extendColumnStore`
+     * call for the whole batch (Phase C prewarm, #213). See
+     * `ArchetypeGraph.createManyFromMasks`. */
     archCreateManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
-    /** Hash-bucketed mask → ArchetypeID lookup; null when the mask isn't planted. */
-    private archLookup;
-    /** Walk the mask's set bits and resolve each non-tag component to its
-     * layout. Used by both single and bulk archetype-create paths. */
-    private archBuildLayouts;
     /** Snapshot every existing archetype's SAB rows, call `extendColumnStore`
      * once with `newSpecs`, then refresh every pre-existing SAB-backed
      * Archetype's TypedArray views. The single `existing` snapshot is the
      * key win in the bulk variant — single-mask creation rebuilds it per
      * call (i.e. N times for N new archetypes). */
-    private archExtendStoreWithNewSpecs;
-    /** Materialise the `Archetype` for `id`, register in the archetype map +
-     * component index, and fan into any matching registered queries.
-     *
-     * Clones `mask` before storing — callers may pass scratch BitSets that
-     * they intend to reuse (e.g. `addComponents` / `removeComponents`'s
-     * `_scratchTargetMask`). The Archetype and the archetypeMap bucket
-     * both keep references long-term, so the clone is required for
-     * correctness — and is the previously-implicit guarantee made by the
-     * mask-allocating callers (`copyWithSet`, `copyWithClear`, etc.). */
-    private archInstall;
-    /** Resolve "add component_id to archetype_id" → target ArchetypeID. Caches the edge. */
+    private _archExtendStoreWithNewSpecs;
+    /** Materialise the `Archetype` object for a freshly-minted graph node —
+     * binds the graph's topology to THIS store's column backing and grow
+     * handler (`ArchetypeGraphHost.materialize`). Store-owned so the graph
+     * never touches `_columnStore`. */
+    private _materializeArchetype;
+    /** Push a newly-installed archetype into every registered query whose masks
+     * it satisfies (`ArchetypeGraphHost.fanIntoQueries`; the query registry
+     * stays on Store). No epoch bump — see the note in `ArchetypeGraph.install`. */
+    private _fanIntoQueries;
+    /** Resolve "add component_id to archetype_id" → target ArchetypeID (edge-cached). */
     private archResolveAdd;
-    /** Resolve "remove component_id from archetype_id" → target ArchetypeID. Caches the edge. */
+    /** Resolve "remove component_id from archetype_id" → target ArchetypeID (edge-cached). */
     private archResolveRemove;
-    /** Cache a bidirectional add/remove edge between two archetypes. */
-    private archCacheEdge;
     createEntity(): EntityID;
-    /** Slot index of the entity allocated by the most recent `_allocEntity`
-     * call. Read immediately after the call (alloc-free out-param). */
-    private _spawnIndex;
     /** Allocate an entity slot WITHOUT placing it in the empty archetype, for
-     * the template spawn paths. Returns the packed `EntityID`; the slot index is
-     * left in `_spawnIndex`. Mirrors `createEntity`'s allocator but skips the
-     * empty-archetype membership write (the caller installs the real archetype
-     * + row). Kept separate from `createEntity` so that hot path stays inline
-     * (#368). This *commits* the slot (bumps counts, stamps the generation so
-     * `isAlive` is already true), so the caller MUST have reserved the column
-     * capacity for the row first (`Archetype.ensureRowCapacity`) — otherwise a
-     * cap throw from the subsequent append leaves the slot phantom-alive (#775). */
+     * the template spawn paths. Returns the packed `EntityID`; the slot index
+     * is left in `entityAllocator.lastIndex`. Skips the empty-archetype
+     * membership write `createEntity` performs (the caller installs the real
+     * archetype + row). This *commits* the slot (bumps counts, stamps the
+     * generation so `isAlive` is already true), so the caller MUST have
+     * reserved the column capacity for the row first
+     * (`Archetype.ensureRowCapacity`) — otherwise a cap throw from the
+     * subsequent append leaves the slot phantom-alive (#775). */
     private _allocEntity;
     /** Pre-check that `count` fresh entity slots can be allocated without
      * exhausting the entity-index space, so `spawnMany` commits all-or-nothing
@@ -490,9 +464,16 @@ export declare class Store {
      * column index; `TEMPLATE_OVERRIDE_AMBIGUOUS` for a name shared by more than
      * one component, which a flat override cannot target). */
     resolveTemplate<Defs extends readonly ComponentDef[]>(entries: TemplateEntries<Defs>): Template<Defs>;
+    /** Resolve an override key to its flat column index, with the DEV guards
+     * for unknown and ambiguous field names; `-1` means skip (the production
+     * fallback where DEV would have thrown). */
+    private _resolveOverrideColumn;
     /** Apply per-instance overrides to the freshly-spawned row. Each key is a
      * field name resolved through the template's override index. */
     private _applyOverrides;
+    /** Bulk variant of `_applyOverrides`: one `fill` per overridden column
+     * across the contiguous rows `[start, start + count)`. */
+    private _applyOverridesRange;
     /** Spawn one entity directly into the template's archetype (zero archetype
      * transitions). Writes the template defaults in a single append pass, then
      * applies any per-instance overrides. */
@@ -501,7 +482,7 @@ export declare class Store {
      * field writes are O(columns) — one `TypedArray.fill` per column via
      * `addEntitiesWithValues` — not O(count×columns). Returns the new ids in
      * spawn order. */
-    spawnMany(p: Template, count: number): EntityID[];
+    spawnMany(p: Template, count: number, overrides?: Record<string, number | undefined>): EntityID[];
     /** Immediately destroy an entity, removing it from its archetype.
      *
      * With no `delete`/`clear` target-cleanup policy registered (the common
@@ -603,7 +584,7 @@ export declare class Store {
     private _onArchEnabledChange;
     /** Immediately disable an entity (idempotent). The entity must hold at least
      * one component — a component-less entity occupies no archetype row, so it
-     * cannot be partitioned (a `__DEV__` error; prod no-op). */
+     * cannot be partitioned (a `DEV` error; prod no-op). */
     disableEntity(id: EntityID): void;
     /** Immediately enable an entity (idempotent). */
     enableEntity(id: EntityID): void;
@@ -665,17 +646,22 @@ export declare class Store {
      * the identity of what was destroyed, not a live handle to read. The
      * no-observer path is byte-for-byte unchanged (`collecting` gate). #531.
      *
-     * Re-entrancy: while the observed fixed point owns the flush
-     * (`_flushingStructural`), the loop drains destroys itself via
-     * `_drainDestroyed`, so a re-entrant `ctx.flush()` from a callback no-ops
-     * here — otherwise it would collect into the shared `_obsEvents` scratch
-     * mid-dispatch and corrupt it (mirrors the `flushStructural` guard). */
+     * Re-entrancy: while the observed fixed point owns the flush, the loop
+     * drains destroys itself via `_drainDestroyed`, so a re-entrant
+     * `ctx.flush()` from a callback no-ops (the guard lives in
+     * `DeferredCommandBuffer.flushDestroyed`) — otherwise it would collect
+     * into the shared `_obsEvents` scratch mid-dispatch and corrupt it. */
     flushDestroyed(): void;
     private _drainDestroyed;
     get pendingDestroyCount(): number;
     addComponentDeferred(entityId: EntityID, def: ComponentDef<Record<string, never>>): void;
     addComponentDeferred<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): void;
     removeComponentDeferred(entityId: EntityID, def: ComponentDef): void;
+    /** Phase-boundary structural flush. The drain policy — no-observer fast
+     * path, observed fixed point (adds/removes → destroys → toggles),
+     * convergence guard, re-entrancy — lives in `DeferredCommandBuffer`
+     * (H1 step 4); the batch appliers it drives are the `_flush*` /
+     * `_drainDestroyed` methods below. */
     flushStructural(): void;
     /** Batch-apply all deferred component additions. */
     private _flushAdds;
@@ -714,7 +700,10 @@ export declare class Store {
      * absent at seed (the "delete on disable" semantics). Unordered here — the
      * registry radix-sorts. */
     _collectEntitiesWithComponent(cid: number): EntityID[];
-    registerComponent<S extends Record<string, TypedArrayTag>>(schema: S): ComponentDef<S>;
+    registerComponent<S extends Record<string, TypedArrayTag>>(schema: S, name?: string): ComponentDef<S>;
+    /** `'Pos' (component 5)` when the component was registered with a debug
+     * name, else `component 5` — the label diagnostics interpolate. */
+    componentLabel(cid: number): string;
     /** Return the field index assigned to `(def, fieldName)` at component
      * registration. Indexes are insertion-order, zero-based, and stable for
      * the lifetime of the ECS. Used by systems that pass `(component_id,
@@ -724,7 +713,9 @@ export declare class Store {
      * allocates from a separate id space and never touches the archetype mask,
      * so it does **not** count against `STORE_DESCRIPTOR_COMPONENT_LIMIT`. See
      * ADR-0011 and `sparse_store.ts`. */
-    registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S): SparseComponentDef<S>;
+    registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S, name?: string): SparseComponentDef<S>;
+    /** Sparse sibling of `componentLabel` — sparse ids are a separate id space. */
+    sparseLabel(sid: number): string;
     /** Allocate the backing sparse store WITHOUT the #777 float guard, for
      * engine-internal backings whose `f64` holds an EXACT integer rather than a
      * user quantity: the exclusive-relation `{ target }` slot stores an `EntityID`
@@ -738,6 +729,7 @@ export declare class Store {
     addSparse(entityId: EntityID, def: SparseComponentDef, values?: Record<string, number>): void;
     /** Remove a sparse component from an entity. No-op if absent. */
     removeSparse(entityId: EntityID, def: SparseComponentDef): void;
+    /** Total, like `hasComponent` — `false` for a dead entity, never a throw. */
     hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
     getSparseField(entityId: EntityID, def: SparseComponentDef, field: string): number;
     setSparseField(entityId: EntityID, def: SparseComponentDef, field: string, value: number): void;
@@ -774,13 +766,6 @@ export declare class Store {
      * Store was constructed with `{ deterministic: true }`; paired with
      * `snapshotSparse`, which produces the canonical bytes restore consumes. */
     restoreSparse(bytes: Uint8Array): void;
-    /** Rebuild every relation's derived side indices after the sparse stores have
-     * been restored. `restoreRelations` resets all relations, rebuilds the multi
-     * forward sets + their reverse edges from `relBytes`, and validates shape.
-     * The exclusive reverse index can't be carried in the bytes (it's derivable),
-     * so it's rebuilt here from the backing sparse store: every member row holds
-     * `(source index → target EntityID)`, which is exactly one reverse edge. */
-    private _rebuildRelationIndices;
     /**
      * Capture the full live world to one self-contained byte buffer that
      * `restoreInto` can mount back onto a live, ticking world ("rewind a running
@@ -802,9 +787,6 @@ export declare class Store {
      * are scheduling artifacts, never folded into `stateHash`. Take the snapshot
      * at a tick boundary (between `update()`s). See the ADR. */
     snapshot(): Uint8Array;
-    /** Gather the host-side state a snapshot carries alongside the dense + sparse
-     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
-    private _collectHostState;
     /**
      * Mount a `snapshot()` buffer onto this live world and leave it ready to keep
      * ticking. Fails closed on a malformed frame or a registration mismatch
@@ -818,15 +800,12 @@ export declare class Store {
      * entity-index capacity. **Opt-in (ADR-0020):** throws `DETERMINISM_DISABLED`
      * unless `{ deterministic: true }`. See `snapshot()` for the v1 scope. */
     restoreInto(bytes: Uint8Array): void;
-    /** Read-only validation of a `snapshotSparse` SECTION (the framed
-     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
-     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
-     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
-     * sparse-stores sub-section without mutating. A relation-registration difference
-     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
-     * differing relation set changes the sparse store count / schema. Throws
-     * `SparseRestoreError` on a mismatch. */
-    private _assertSparseSectionMatches;
+    /** Adopt a restored dense store (`SnapshotService.restoreInto`'s mount
+     * step): swap the live backing, refresh every buffer-backed archetype's
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Store-owned because it assigns
+     * `_columnStore` — the service never writes Store fields. */
+    private _mountRestoredDense;
     /** Rebuild each SAB-backed archetype's host-side `length` / `enabledCount` /
      * `_entityIds` after the dense backing was swapped in `restoreInto`. `length`
      * + the per-row entity-id back-reference come from a scan of the restored
@@ -834,167 +813,26 @@ export declare class Store {
      * from the captured host-state (the #577 partition boundary is positional only
      * — it has no per-entity byte source). */
     private _reconstructHostRows;
-    /** Register a relation kind. `exclusive` (the default) → one target per
-     * source, stored in a backing `{ target: f64 }` sparse component, so the
-     * forward index rides the sparse store and inherits query membership (#469),
-     * `stateHash` + snapshot/restore (#470) for free. `multi` → a set of
-     * targets per source, backed by a sparse tag for membership plus a side
-     * forward index the relation owns. The two cardinalities are mutually
-     * exclusive. `onDeleteTarget` selects the cleanup policy run when a target
-     * is destroyed — `delete` (cascade-destroy sources), `clear` (drop the link,
-     * sources survive), or `orphan` (default: leave it dangling, #473). See
-     * ADR-0011 and `relation.ts`.
-     *
-     * The backing sparse store is resolved and handed to the relation so it can
-     * drive forward/membership rows directly — the cardinality-specific
-     * interaction is `ExclusiveRelationStore` / `MultiRelationStore`'s, not a
-     * branch here (#498). */
     registerRelation(opts?: RelationOptions): RelationDef;
-    private relationOf;
     /** Number of registered relations. Visible to tests asserting the
      * no-transition invariant alongside `archetype_count`. */
     get relationCount(): number;
-    /** Add a `(R, tgt)` pair to `src`. No archetype transition. Exclusive:
-     * replaces any existing target (engine-enforced one-per-source), a no-op if
-     * `tgt` is already the target. Multi: adds `tgt` to the set, a no-op if
-     * already present. A dead `src` *or* `tgt` is caller error: it throws in
-     * `__DEV__` and is a no-op in production — symmetric, so a production build
-     * never links a reverse-index entry keyed by a destroyed handle (#495). */
     addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
-    /** Remove a `(R, tgt)` pair from `src`. No archetype transition. Exclusive:
-     * `tgt` is optional and the removal is a no-op when it names a target other
-     * than the current one. Multi: omitting `tgt` removes *all* of `src`'s
-     * targets; passing one removes just that pair (dropping membership when the
-     * set empties). */
     removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
-    /** The single target of `src` under an exclusive relation, or `undefined`.
-     * Throws in `__DEV__` on a multi-target relation (use `targetsOf`). */
     targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
-    /** All targets of `src` under `R` — one or zero for exclusive, the full set
-     * for multi — ascending by id. */
     targetsOf(src: EntityID, def: RelationDef): EntityID[];
-    /** Sources that point at `tgt` under `R` (the reverse index), ascending by
-     * id; empty when none. */
-    sourcesOf(def: RelationDef, tgt: EntityID): EntityID[];
-    /** Whether `src` holds any pair under `R`. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
     hasRelation(src: EntityID, def: RelationDef): boolean;
-    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
-     * (#472). Sources are emitted in **canonical entity-index order** (the #470
-     * determinism convention): exclusive relations ride the backing sparse
-     * store's `canonicalIndices`, multi relations ride the same
-     * `forEachCanonicalTargetSet` traversal `stateHash` / `snapshotRelations`
-     * use; a multi source's targets follow ascending by id. Empty when the
-     * relation holds no pairs. Cold path — allocates the result array (and, for
-     * multi, sorts each source's target set); not for per-tick use. The
-     * point-query forms are `targetOf` / `targetsOf`. */
-    pairsOf(def: RelationDef): [EntityID, EntityID][];
-    /** Every `(relation, source)` pointing at `tgt`, across **all** registered
-     * relation kinds — the `(*, T)` wildcard (#472). Walks the relation registry
-     * in id order (each relation's reverse index already returns sources
-     * ascending by id), so the result is ordered by relation id then source id.
-     * Empty when nothing targets `tgt`. The single-relation form is
-     * `sourcesOf(def, tgt)`. */
-    sourcesOfAny(tgt: EntityID): [RelationDef, EntityID][];
-    /** The backing sparse component id of relation `R` — the membership store a
-     * `(R, *)` wildcard term (`Query.withRelation`) drives through the shared
-     * sparse-match path. Exclusive relations back a `{ target: f64 }` sparse
-     * component, multi a tag; both carry per-source membership, so "has any
-     * `(R, *)` pair" is exactly membership in this store (including an
-     * orphan-dangling source, whose membership row persists — consistent with
-     * `pairsOf`). The def is engine-owned and never handed to callers; this hands
-     * the query builder only its erased id for the `sparseInclude` list. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
     relationBackingSparseId(def: RelationDef): SparseComponentID;
-    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`): every source
-     * related to `target` under **any** relation, intersected with the query's
-     * dense mask + sparse require/exclude terms + the default enabled-row filter,
-     * each source yielded once. Unions `sourcesOf(R, target)` across every
-     * relation into a `Set` (dedup by full `EntityID` — a source related to `T`
-     * via two relations is yielded once), then sorts ascending: the cross-relation
-     * union has no inherent order, so one cold sort gives a deterministic,
-     * canonical `(*, T)` order matching `sourcesOf` / `sourcesOfAny` (which sort
-     * the same way). Cold/structural — not a per-tick hot loop over many targets.
-     * `sparseInclude`/`sparseExclude` carry both raw sparse terms and the backing
-     * stores of any composed `(R, *)` terms, so it intersects with them uniformly. */
+    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`) — see
+     * `RelationService.forEachRelationTargetMatch`. */
     _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
-    /** Reclaim reverse-index memory: drop every relation's reverse entries whose
-     * **target** has been destroyed, returning the total dropped across all
-     * relations (#491). Under the default `orphan` policy a destroyed target
-     * leaves its reverse entry intact until each source re-targets or dies, so a
-     * long-lived source that orphan-points at a churn of short-lived targets and
-     * never re-targets accumulates dead-target keys without bound. This cold-path
-     * hook drops them on demand — call it at scene or snapshot boundaries.
-     *
-     * Purely a memory reclaim with no observable state change: forward links stay
-     * dangling (so `orphan`'s `targetOf`-returns-the-dead-handle contract is
-     * unchanged), `stateHash` is unaffected (the reverse index is derived, never
-     * folded), and the dropped entries are faithfully rebuilt by snapshot/restore
-     * from the surviving forward links (`_rebuildRelationIndices`). The only
-     * difference a caller can see is `sourcesOf(R, deadHandle)` going from the
-     * dangling sources to `[]` — both meaningless once the target is gone.
-     * No-op (returns 0) when no relations are registered. */
     compactRelations(): number;
-    /** Walk exclusive relation `R` from `src` toward the root, returning the
-     * **up**-chain `[src, parent, grandparent, …, root]` (nearest-ancestor-first,
-     * inclusive of both endpoints). A source with no target returns `[src]`. The
-     * root is the first entity in the chain with no `R`-target, **or** a dangling
-     * dead target handle (see below). Throws `RELATION_MODE_MISMATCH` on a multi
-     * relation and `RELATION_CYCLE` on a cycle (both `__DEV__`-only; in production
-     * a cycle stops at the repeated node).
-     *
-     * **Dangling links terminate the chain.** Under the `orphan` policy a source
-     * keeps pointing at a destroyed target (a dead handle). The walk must *not*
-     * advance through such a handle: the backing store is keyed by entity
-     * **index**, so reading the dead handle's index would return whatever now
-     * occupies that recycled slot — splicing the chain onto an unrelated entity
-     * (the ABA the `EntityID`-keyed reverse index avoids for `cascadeOf`). So a
-     * dead next-hop is appended as the chain's (dangling) terminus and the walk
-     * stops; the caller can detect it with `isAlive`, exactly as `targetOf`
-     * returns a dead handle. */
     ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
-    /** The root of `src`'s exclusive-relation chain — the last entity of
-     * `ancestorsOf` (the one with no `R`-target). `src` itself when it has no
-     * target. If the chain ends in a dangling dead target handle (orphan policy),
-     * that handle is the root — `isAlive`-check the result if dangling links are
-     * possible. Same `__DEV__` guards as `ancestorsOf`. */
     rootOf(src: EntityID, def: RelationDef): EntityID;
-    /** Walk exclusive relation `R` **down** from `root` over the reverse index,
-     * returning the subtree (including `root`) breadth-first — **parents before
-     * children** (the `cascade` order). Children of each node come from
-     * `sourcesOf` (ascending by id), so the traversal is deterministic. Throws
-     * `RELATION_MODE_MISMATCH` on a multi relation and `RELATION_CYCLE` on a cycle
-     * (both `__DEV__`-only; in production an already-visited node is skipped, so
-     * it never hangs). */
     cascadeOf(root: EntityID, def: RelationDef): EntityID[];
-    /** Purge a destroyed entity from the relation indices — its **source** role
-     * only: drop its forward target(s) and unlink it from every target's reverse
-     * set. The backing sparse membership row is dropped separately by
-     * `_purgeSparse`, so this must run *before* it (it reads the sparse target
-     * field for exclusive relations). The entity's **target** role is left
-     * intact: the reverse index is keyed by full `EntityID`, so a recycled slot
-     * never aliases the dead target's sources. The destroyed entity's **target**
-     * role is handled separately by `_cleanupRelationTargets` per each
-     * relation's `OnDeleteTarget` policy (#473). Gated by the caller on
-     * `relations.length > 0`. */
-    private _purgeRelations;
-    /** Apply each relation's `OnDeleteTarget` policy for a destroyed **target**
-     * `targetId` (#473). Walks the registry; for every relation whose reverse
-     * index has sources pointing at the dead target:
-     *
-     *  - **`delete`** — append each source to `cascade`; the caller destroys them
-     *    through the same path, so chains/trees cascade recursively. The sources'
-     *    own source-role purge (`_purgeRelations`) drops their forward link and
-     *    unlinks them from `targetId`'s reverse set, so no reverse entry leaks.
-     *  - **`clear`** — drop each source's link to the dead target in place via
-     *    `rs.unlink(src, targetId)` (exclusive drops the row; multi removes the
-     *    target from the set, dropping membership when it empties). Sources
-     *    survive — the cardinality bookkeeping is the relation's, not branched here.
-     *  - **`orphan`** — skipped (the link is left dangling; safe because the
-     *    reverse key carries the generation).
-     *
-     * `sourcesOf` returns a fresh snapshot, so mutating the reverse index while
-     * iterating is safe. Gated by the caller on `_hasTargetCleanup`, so the
-     * whole walk is skipped when no relation opts into a non-`orphan` policy. */
-    private _cleanupRelationTargets;
     /** Second query-match path (#469 / ADR-0011): iterate entities matching a
      * dense mask **and** sparse-membership terms, invoking `cb` per entity.
      * Yields `EntityID`s, not archetype spans — sparse members are scattered
@@ -1013,44 +851,9 @@ export declare class Store {
      * Only reached via `Query.forEachEntity`; dense `forEach` never consults
      * the sparse stores, so dense-only queries are unaffected (#469 AC). */
     _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;
-    /** Fourth query-match path (#581): yield the matched entities — the exact
-     * `_forEachSparseMatch` intersection (dense mask + sparse require/exclude +
-     * the default enabled-row filter) — in canonical **hierarchy depth order** over
-     * exclusive relation `R`: depth ascending (parents before children), **entity
-     * index ascending within each depth band**. Entities deeper than `maxDepth`
-     * are skipped (`Infinity` = unbounded). Only reached via `Query.forEachEntity`
-     * on a query carrying a `.hierarchy(R)` term.
-     *
-     * `.hierarchy(R)` does not narrow the matched set — it reorders it — so an
-     * entity with no `R`-parent is a root (depth 0) and is yielded first. Depth is a
-     * structural property of the *full* tree (an ancestor outside the matched set
-     * still counts toward depth), computed by a memoised upward walk shared across
-     * the whole batch, so a shared/deep chain costs O(nodes), not O(nodes²).
-     *
-     * The canonical order is produced without a comparator sort (which the observer
-     * bench measured at 2–4× — `observer.ts`): (1) collect the matched ids via
-     * `_forEachSparseMatch`; (2) `radixSortByIndex` → entity-index ascending;
-     * (3) stable-bucket by depth — since the input is index-ascending and the bucket
-     * append is stable, each depth band stays index-ascending. Tuned for the
-     * motivating per-tick case (transform propagation): the radix scratch is reused
-     * instance state (`_hierarchy_radix_*`), so a per-tick pass churns no histograms;
-     * the working set (`matched` / `buckets` / `depthMemo` / `visiting`) is still
-     * allocated per call, as it must stay call-local for re-entrancy.
-     *
-     * Exclusive-only — a multi relation throws `RELATION_MODE_MISMATCH` in `__DEV__`
-     * (mirrors `cascadeOf` / `ancestorsOf`); a cycle is a loud `RELATION_CYCLE` in
-     * `__DEV__` and a safe break in production. */
+    /** Fourth query-match path (#581): the matched set in hierarchy depth order
+     * (parents before children) — see `RelationService.forEachHierarchyMatch`. */
     _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;
-    /** Depth of entity index `idx` in the exclusive-relation tree backing `store`
-     * (root = 0), for `_forEachHierarchyMatch`. Memoised across the batch (`memo`),
-     * so a shared ancestor chain is walked once. Walks upward via the backing store's
-     * target field 0 (mirroring `ancestorsOf`), stopping at: a root (no target), an
-     * already-memoised node, or a dangling/dead parent (the child is then treated as
-     * a root — never advance through a recycled slot, the ABA `ancestorsOf` guards).
-     * `visiting` flags the nodes on the current upward path to catch a cycle —
-     * `RELATION_CYCLE` in `__DEV__`, treated as a root in production — and is emptied
-     * on the way back down so it can be reused for the next entity. */
-    private _hierarchyDepthOf;
     addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): void;
     addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): void;
     /** Add multiple components in one transition (resolves final archetype, then moves once).
@@ -1066,7 +869,7 @@ export declare class Store {
      * archetypes the entity never visits.
      *
      * #659 — composite-add edge cache. The final-mask resolve, unlike the
-     * single-add `edges[]` walk, re-pays a per-call `mask.hash()`, `archLookup`
+     * single-add `edges[]` walk, re-pays a per-call `mask.hash()`, `ArchetypeGraph.lookup`
      * (the Map-of-buckets + `equals` scan), and `getBatchTransitionMap` on
      * every call — a ~2× gap vs a cached edge walk that the decomposition probe
      * pinned on the two `Map.get`s, not the hash. So a repeated (source, added-
@@ -1075,10 +878,7 @@ export declare class Store {
      * skip the union-mask build entirely. First call per key still resolves via
      * the final-mask path below (no intermediate planting) and plants the edge.
      * See docs/reports/bench/regressions/add-components-composite-edge.md. */
-    addComponents(entityId: EntityID, entries: {
-        def: ComponentDef;
-        values?: Record<string, number>;
-    }[]): void;
+    addComponents<Defs extends readonly ComponentDef[]>(entityId: EntityID, entries: TemplateEntries<Defs>): void;
     /** Shared move+write tail of `addComponents` (#659): place the entity into
      * the already-resolved `targetArch` — a `moveEntityFrom` along the cached
      * `map` when it has a row, else a fresh append (the rowless empty-archetype
@@ -1095,7 +895,10 @@ export declare class Store {
      * removal path. Computing the difference mask up front and resolving
      * once avoids planting N-1 intermediates the entity never lives in. */
     removeComponents(entityId: EntityID, defs: ComponentDef[]): void;
-    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    /** Total (POLISH_AUDIT #9): a dead/stale `entityId` returns `false` rather
+     * than throwing — a "has" probe is exactly what callers reach for to avoid
+     * touching dead entities, so it must be safe to ask. */
+    hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
     /**
      * Bulk add a component to ALL entities in the given archetype.
      * Uses TypedArray.set() for O(columns) instead of O(N×columns).
@@ -1123,25 +926,23 @@ export declare class Store {
     registerQuery(include: BitSet, exclude?: BitSet, anyOf?: BitSet): Archetype[];
     updateQueryRef(result: Archetype[], query: Query<any>): void;
     get archetypeCount(): number;
-    registerEvent<S extends EventSchema>(fields: readonly (keyof S & string)[]): EventDef<S>;
-    emitEvent(def: EventDef, values: Record<string, number>): void;
+    registerEvent<S extends EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    emitEvent(def: EventDef<any>, values: Record<string, number>): void;
     emitSignal(def: EventDef<EmptyEventSchema>): void;
-    getEventReader<S extends EventSchema>(def: EventDef<S>): EventReader<S>;
+    getEventReader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
     clearEvents(): void;
-    /** `__DEV__`-only: total events currently buffered across the dirty channels.
-     * `ECS.update` samples this either side of `dispatchSet` to assert an onSet
-     * observer emitted nothing — its emissions would be wiped by the tick-tail
-     * `clearEvents` and break the empty-channel-at-boundary invariant snapshot /
-     * restore relies on (#586). Walks only the dirty list, never the hot emit path. */
+    /** `DEV`-only mid-update emit detection — see
+     * `EventRegistry.devBufferedEventCount`. */
     _devBufferedEventCount(): number;
-    private readonly eventKeyMap;
-    registerEventByKey<S extends EventSchema>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    registerEventByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
     getEventDefByKey(key: symbol): EventDef<any>;
     hasEventKey(key: symbol): boolean;
-    private readonly resourceKeyMap;
+    private readonly resources;
     registerResource(key: symbol, value: unknown): void;
     getResource(key: symbol): unknown;
     setResource(key: symbol, value: unknown): void;
+    /** Fails closed on a missing key; the present → absent → present
+     * lifecycle (#798) — see `ResourceRegistry.remove`. */
     removeResource(key: symbol): void;
     hasResource(key: symbol): boolean;
 }