@oasys/oecs 0.4.0 → 0.5.0

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

@@ -1,24 +1,28 @@
-import { Template, TemplateEntries, TemplateOverrides } from './store';
-import { FrameTraceSink } from './frame_trace';
-import { ObserverHandle, EntitySetObserverConfig, ArchetypeSetObserverConfig, StructuralObserverConfig } from './observer';
-import { ColumnStore, ColumnStoreRegionHandle, StoreRegionSpec } from '../store';
-import { SCHEDULE, SystemEntry, SystemSet, SystemSetConfig } from './schedule';
-import { Archetype, ArchetypeID } from './archetype';
-import { SystemContext, Query, QueryBuilder, ChangedQuery, QueryResolver } from './query';
-import { EntityID } from './entity';
-import { ComponentDef, ComponentSchema, FieldValues, BundleOrDef } from './component';
-import { SparseComponentDef, SparseComponentID } from './sparse_store';
-import { RelationDef, RelationOptions } from './relation';
-import { EventKey, EventReader, EventSchema, SignalKey } from './event';
-import { ResourceKey } from './resource';
-import { SystemFn, SystemConfig, SystemDescriptor } from './system';
-import { BitSet, TypedArrayTag } from '../../type_primitives';
-import { StoreLayoutListener } from './store_layout_listener';
-import { ComputeBackend } from './compute_backend';
-import { ResolvedECSMemory, ECSMemoryOptions } from './ecs_memory';
+import { Template, TemplateEntries, TemplateOverrides } from './store.js';
+import { FrameTraceSink } from './frame_trace.js';
+import { ObserverHandle, EntitySetObserverConfig, ArchetypeSetObserverConfig, StructuralObserverConfig } from './observer.js';
+import { ColumnStore, ColumnStoreRegionHandle, StoreRegionSpec } from '../store/index.js';
+import { ECSRelations, ECSEvents, ECSResources, ECSSnapshots } from './facades.js';
+import { SCHEDULE, SystemEntry, SystemSet, SystemSetConfig } from './schedule.js';
+import { Archetype, ArchetypeID } from './archetype.js';
+import { SystemContext, Query, QueryBuilder, QueryCache, QueryResolver } from './query.js';
+import { EntityID } from './entity.js';
+import { ReadonlyComponentRef } from './ref.js';
+import { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, CompleteFieldValues, Bundle, BundleOrDef } from './component.js';
+import { SparseComponentDef, SparseComponentID } from './sparse_store.js';
+import { RelationDef } from './relation.js';
+import { SystemFn, SystemConfig, SystemDescriptor, TypedSystemConfig, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.js';
+import { BitSet, TypedArrayTag } from '../../type_primitives/index.js';
+import { StoreLayoutListener } from './store_layout_listener.js';
+import { ComputeBackend } from './compute_backend.js';
+import { ResolvedECSMemory, ECSMemoryOptions } from './ecs_memory.js';
 export interface ECSOptions {
     fixedTimestep?: number;
     maxFixedSteps?: number;
+    /** Sink for dev-mode engine diagnostics (currently the schedule's
+     * dropped-ordering-edge warning). Defaults to `console.warn`. Mirrors the
+     * `FrameTraceSink` seam's injectable style — no global logger. */
+    onWarn?: (message: string) => void;
     /** How the world's memory is sized and backed (#682) — the single
      * sizing surface, replacing the pre-release `initialCapacity` +
      * `bufferAllocator` pair. Express intent through exactly one arm:
@@ -64,26 +68,28 @@ export declare class ECS implements QueryResolver {
     /** Component observers (#517 §1 / ADR-0013). Inert until `observe(...)` is
      * called — the structural-flush fast path is byte-for-byte unchanged. */
     private readonly _observers;
+    /** Relations: register/add/remove/has, wildcard + traversal reads,
+     * reverse-index compaction. See `ECSRelations`. */
+    readonly relations: ECSRelations;
+    /** Host-side event channels + signals: register/registerSignal/emit/read
+     * (system-side `ctx.emit` is unchanged). See `ECSEvents`. */
+    readonly events: ECSEvents;
+    /** World resources: register/get/set/remove/has. See `ECSResources`. */
+    readonly resources: ECSResources;
+    /** Determinism surface: capture/restore (full + sparse), stateHash,
+     * the `deterministic` flag. See `ECSSnapshots`. */
+    readonly snapshots: ECSSnapshots;
     private readonly systems;
     private nextSystemId;
     private _tick;
+    private _updating;
     private _fixedTimestep;
     private _accumulator;
     private _maxFixedSteps;
-    private readonly queryCache;
     private readonly scratchMask;
     private _nextQueryIdCounter;
-    readonly _andSingleCache: Map<number, Query<any>>;
-    readonly _notSingleCache: Map<number, Query<any>>;
-    readonly _anyOfSingleCache: Map<number, Query<any>>;
-    readonly _changedSingleCache: Map<number, ChangedQuery<any>>;
-    readonly _withSparseSingleCache: Map<number, Query<any>>;
-    readonly _withoutSparseSingleCache: Map<number, Query<any>>;
-    readonly _withRelationSingleCache: Map<number, Query<any>>;
-    readonly _withoutRelationSingleCache: Map<number, Query<any>>;
-    readonly _optionalSingleCache: Map<number, Query<any>>;
-    readonly _includeDisabledSingleCache: Map<number, Query<any>>;
-    readonly _hierarchySingleCache: Map<number, Query<any>>;
+    /** @internal Query-composition caches (QueryResolver seam) — not public API. */
+    readonly _caches: QueryCache;
     private readonly _layoutSubscribers;
     private _backend;
     private readonly _memory;
@@ -98,16 +104,6 @@ export declare class ECS implements QueryResolver {
      * share the same bytes. */
     get wasmMemory(): WebAssembly.Memory | null;
     constructor(options?: ECSOptions);
-    /** Resolve a consumer-declared SAB region's byte offset by `region_id`, or
-     * 0 when absent. Generic, de-gamed replacement (#623) for the removed
-     * game-named accessors; pair with the consumer's own region module to
-     * materialise a typed view. Delegates to `Store.regionOffset`. */
-    regionOffset(regionId: number): number;
-    /** A handle (`{ buffer, view, offset, bytes }`) to a consumer-declared SAB
-     * region resolved by `region_id`, or `null` when absent. A consumer's
-     * region module builds a TypedArray view over the region's span from this.
-     * Re-fetch after a SAB grow. Delegates to `Store.regionHandle`. (#623) */
-    regionHandle(regionId: number): ColumnStoreRegionHandle | null;
     /** Batch variant of `regionHandle` for hosts wiring several consumer
      * regions at startup: returns the handles in argument order, never null —
      * throws ONE `REGION_NOT_DECLARED` naming every missing region id instead
@@ -137,44 +133,12 @@ export declare class ECS implements QueryResolver {
      * the schedule to the pure-TS path.
      *
      * One backend per ECS: attaching while one is already attached throws in
-     * `__DEV__` (detach first). The engine never inspects the backend beyond
+     * `DEV` (detach first). The engine never inspects the backend beyond
      * `setLayout` / `run` — it carries no game vocabulary. */
     attachBackend(backend: ComputeBackend): () => void;
-    /** Look up the field index a component reserves for `fieldName`. The
-     * index is assigned by `registerComponent` in insertion order and is
-     * stable for the lifetime of the ECS. Used by systems that need to
-     * pass `(component_id, field_id)` pairs across the WASM FFI — the Zig
-     * side identifies columns by these numeric IDs. */
-    fieldId<S extends Record<string, TypedArrayTag>>(def: ComponentDef<S>, fieldName: Extract<keyof S, string>): number;
-    /** Resolve an archetype's row index to the `EntityID` at that slot.
-     * A WASM system that drains events from the event ring as
-     * `(archId, row, …)` payloads uses this to convert the (archId, row)
-     * pair into the `EntityID` the `ctx.emit(...)` API expects.
-     * Throws if the (archId, row) pair is out of range. (#250 / Phase 4
-     * PR 4D) */
-    entityIdAtRow(archetypeId: number, row: number): EntityID;
     get fixedTimestep(): number;
     set fixedTimestep(value: number);
     get fixedAlpha(): number;
-    /** The single SAB backing every archetype's column views. Exposed for
-     * snapshot/restore, `columnStoreStateHash`-based determinism checks, and
-     * Phase 2+ WASM/worker hand-off paths. Mutation flows through the
-     * usual `addComponent` / `removeComponent` / `flush` APIs; readers
-     * that hold a column view across a grow must consult
-     * `header.view_stamp` to detect a republish (#171 §8.1). */
-    get columnStore(): ColumnStore;
-    /** Count of live archetypes (including the empty one). Surfaces the
-     * Store-side `archetype_count` so Phase C tests can assert the
-     * pre-warmed closure was materialised; equally useful for diagnostics. */
-    get archetypeCount(): number;
-    /** Count of registered relations (#471). Surfaces the Store-side count so
-     * tests can assert it alongside `archetype_count` when checking the
-     * no-transition invariant. */
-    get relationCount(): number;
-    /** Whether the determinism surface is enabled (#626 / ADR-0020). `false`
-     * (the default) ⇒ `stateHash` / `snapshotSparse` / `restoreSparse` throw
-     * `DETERMINISM_DISABLED`. Opt in via `new ECS({ deterministic: true })`. */
-    get deterministic(): boolean;
     /** Attach (or detach with `null`) a per-world frame-trace sink (ADR-0030):
      * the engine then fires structured `FrameTraceSink` events at each system,
      * flush, command, observer firing, and event during `update()`, so a consumer
@@ -182,110 +146,51 @@ export declare class ECS implements QueryResolver {
      * also receives a `phaseBoundary(phase)` at each phase's post-flush settle
      * point — the safe seam to read `stateHash()` between phases of one frame and
      * bisect a divergence to the exact phase (#797 / ADR-0032). The seam is
-     * `__DEV__`-gated end to end — in a production build this setter keeps an empty
+     * `DEV`-gated end to end — in a production build this setter keeps an empty
      * body and the world never retains a sink. The sink only observes; it does not
      * perturb `stateHash`, ordering, or any behaviour. */
     setTrace(sink: FrameTraceSink | null): void;
-    /** FNV-1a 32 over (archetype_id, live row count, live column bytes)
-     * for every archetype in id order. The canonical "live ECS state
-     * digest" — broader than the pre-#171 per-networked-component fold
-     * (every column contributes, not just BIT_HEALTH / BIT_HEX_POS etc.)
-     * and tighter than `columnStoreStateHash(ecs.columnStore)` (skips trailing
-     * unused SAB capacity). Per-call cost scales with live entity count,
-     * not SAB capacity. (#171 §6.1.9 Phase 5)
-     *
-     * Opt-in (#626 / ADR-0020): throws `DETERMINISM_DISABLED` unless the ECS was
-     * constructed with `{ deterministic: true }`. */
-    stateHash(): number;
-    /** Serialize the sparse stores (out-of-identity components, ADR-0011) to a
-     * self-contained byte buffer — the sparse half of a world snapshot, written
-     * in canonical entity-index order so it's insertion-order-independent
-     * (#470). The dense half is the SAB snapshot (`snapshotColumnStore(columnStore)`).
-     * Pairs with `restoreSparse`.
-     *
-     * Opt-in (#626 / ADR-0020): throws `DETERMINISM_DISABLED` unless the ECS was
-     * constructed with `{ deterministic: true }`. */
-    snapshotSparse(): Uint8Array;
-    /** Repopulate the sparse stores from `snapshotSparse` bytes (full-equality
-     * round-trip of membership + data). Sparse components must already be
-     * registered in the same order; throws `SparseRestoreError` on a shape or
-     * identity mismatch (store/field count, field-identity schema hash, an entity
-     * index past `MAX_INDEX`, or a non-canonical frame with trailing bytes).
-     *
-     * Opt-in (#626 / ADR-0020): throws `DETERMINISM_DISABLED` unless the ECS was
-     * constructed with `{ deterministic: true }`. */
-    restoreSparse(bytes: Uint8Array): void;
-    /** Capture the full live world — dense (SAB columns), sparse + relations, and
-     * the host-side bookkeeping the SAB omits (tick, entity recycle free-list,
-     * alive count, per-archetype row/enabled counts) — to one self-contained byte
-     * buffer that `restoreInto` can mount back onto a live, ticking world
-     * ("rewind a running world and keep ticking", #789). Take it at a tick
-     * boundary (between `update()`s).
+    /**
+     * Register a dense component and get back its typed handle. Record syntax
+     * gives per-field type control; the array shorthand types every field the
+     * same (default `"f64"` — rejected on a `{ deterministic: true }` world
+     * (#777), pass an explicit integer type there). An empty schema `{}` is a
+     * tag. `opts.name` labels dev-mode diagnostics (`'Pos' (component 5)`
+     * instead of `component 5`) — diagnostic only, no behavioural effect.
      *
-     * Opt-in (ADR-0020): throws `DETERMINISM_DISABLED` unless `{ deterministic:
-     * true }`. v1 does NOT capture resources, events, or change-detection /
-     * scheduler baselines (`changed()` queries) — see ADR-0031. */
-    snapshot(): Uint8Array;
-    /** Mount a `snapshot()` buffer onto this live world and leave it ready to keep
-     * ticking (#789). Fails closed on a malformed frame or a registration mismatch
-     * (different component/archetype graph, mismatched entity-index capacity, or a
-     * divergent sparse-store registration) BEFORE mutating any live state — the
-     * guard reads the snapshot's descriptors + sparse-section shape from the bytes,
-     * since the dense build reuses (and overwrites) the live in-place backing.
-     * Throws `WorldRestoreError` (dense) / `SparseRestoreError` (sparse). Requires a
-     * world whose archetype set + column layout match the snapshot's (prewarm so the
-     * set is stable).
+     * The handle is *callable*: `Pos({ x: 1 })` mints a `Bundle` for the
+     * attach surfaces (`spawnBundle`, `ctx.commands.spawn`, `addComponent`).
      *
-     * Opt-in (ADR-0020): throws `DETERMINISM_DISABLED` unless `{ deterministic:
-     * true }`. */
-    restoreInto(bytes: Uint8Array): void;
-    registerComponent<S extends Record<string, TypedArrayTag>>(schema: S): ComponentDef<S>;
-    registerComponent<const F extends readonly string[], T extends TypedArrayTag = "f64">(fields: F, type?: T): ComponentDef<{
+     * @example
+     * const Pos = ecs.registerComponent({ x: "f64", y: "f64" });
+     * const Hp = ecs.registerComponent(["current", "max"], "i32");
+     * const Frozen = ecs.registerComponent({}, { name: "Frozen" }); // tag
+     * ecs.getField(e, Pos, "x"); // field names/types flow from the schema
+     */
+    registerComponent<S extends Record<string, TypedArrayTag>>(schema: S, opts?: ComponentRegisterOptions): ComponentDef<S>;
+    registerComponent<const F extends readonly string[], T extends TypedArrayTag = "f64">(fields: F, type?: T, opts?: ComponentRegisterOptions): ComponentDef<{
         readonly [K in F[number]]: T;
     }>;
-    registerTag(): ComponentDef<Record<string, never>>;
-    registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S): SparseComponentDef<S>;
-    registerSparseComponent<const F extends readonly string[], T extends TypedArrayTag = "f64">(fields: F, type?: T): SparseComponentDef<{
+    registerSparseComponent<S extends Record<string, TypedArrayTag>>(schema: S, opts?: ComponentRegisterOptions): SparseComponentDef<S>;
+    registerSparseComponent<const F extends readonly string[], T extends TypedArrayTag = "f64">(fields: F, type?: T, opts?: ComponentRegisterOptions): SparseComponentDef<{
         readonly [K in F[number]]: T;
     }>;
-    /** Register a sparse tag (empty schema) — membership only, no data. */
-    registerSparseTag(): SparseComponentDef<Record<string, never>>;
-    registerEvent<S extends EventSchema>(key: EventKey<S>, fields: readonly (keyof S & string)[]): void;
-    registerSignal(key: SignalKey): void;
-    registerResource<T>(key: ResourceKey<T>, value: T): void;
-    resource<T>(key: ResourceKey<T>): T;
-    setResource<T>(key: ResourceKey<T>, value: T): void;
-    /** Drop a resource from the world (#798). Unlike {@link registerResource}
-     * — a one-time world-setup op — this is a runtime mutation, so it is access-
-     * checked as a *write* (a system removing a resource must declare it in
-     * `resourceWrites`, which is what serialises it against readers/writers of the
-     * same key). Fails closed on a missing key. Afterwards the key is free to
-     * `registerResource` again — the present → absent → present lifecycle.
-     * Resources are out of `stateHash` and snapshot/resume, so a remove never
-     * perturbs the determinism hash. */
-    removeResource<T>(key: ResourceKey<T>): void;
-    hasResource<T>(key: ResourceKey<T>): boolean;
-    createEntity(): EntityID;
-    createEntity<Defs extends readonly ComponentDef[]>(template: Template<Defs>, overrides?: TemplateOverrides<Defs>): EntityID;
-    /** Register an archetype template (#462). Resolves the component set +
-     * default field values to a target archetype once (creating it if absent —
-     * fits the prewarm model), so later `spawn` / `spawnMany` calls land
-     * entities directly in that archetype with **zero archetype transitions**.
+    /**
+     * Spawn an entity, immediately. Bare `spawn()` creates an empty entity —
+     * attach components afterward. `spawn(template, overrides?)` lands
+     * directly in the template's archetype with zero archetype transitions,
+     * applying optional flat per-field overrides on top of the template
+     * defaults. Inside a system use `ctx.commands.spawn(...)` instead.
      *
-     *   const Bullet = ecs.template([
-     *     { def: Position, values: { x: 0, y: 0 } },
-     *     { def: Velocity, values: { vx: 0, vy: 0 } },
-     *   ]);
+     * @example
+     * const e = ecs.spawn();
+     * ecs.addComponent(e, Pos, { x: 0, y: 0 });
      *
-     * The big win is multi-component entities and bulk spawns; a single-
-     * component spawn is no faster than `createEntity` + `addComponent`, which
-     * already bump-allocates a fresh entity into the target archetype. See
-     * ADR-0010. */
-    template<Defs extends readonly ComponentDef[]>(entries: TemplateEntries<Defs>): Template<Defs>;
-    /** Bulk-spawn `count` identical entities from `template`. Field writes are
-     * O(columns) (one `TypedArray.fill` per column), not O(count×columns).
-     * Returns the new ids in spawn order. */
-    createEntities(template: Template, count: number): EntityID[];
+     * const Bullet = ecs.template([{ def: Pos, values: { x: 0, y: 0 } }]);
+     * const b = ecs.spawn(Bullet, { x: 5 }); // override a template default
+     */
+    spawn(): EntityID;
+    spawn<Defs extends readonly ComponentDef[]>(template: Template<Defs>, overrides?: TemplateOverrides<Defs>): EntityID;
     /**
      * Spawn an entity from varargs bundles (§bundles) — the immediate
      * host-side analog of `ctx.commands.spawn`. `ecs.spawnBundle(bundle(Pos,{x,y}),
@@ -295,81 +200,53 @@ export declare class ECS implements QueryResolver {
      * prototype this mirrors the existing per-component `addComponent` path.
      */
     spawnBundle(...items: BundleOrDef[]): EntityID;
-    /** Buffer an entity for deferred destruction (applied at the next phase
-     *  flush — matches the semantics of `SystemContext.destroyEntity`). The
-     *  ECS surface is unsuffixed because the context (`ECS` vs Store) already
-     *  implies the mode; `Store.destroyEntity` is the immediate path. */
-    destroyEntity(id: EntityID): void;
-    isAlive(id: EntityID): boolean;
-    get entityCount(): number;
-    addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): this;
-    addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: FieldValues<S>): this;
-    addComponents(entityId: EntityID, entries: {
-        def: ComponentDef;
-        values?: Record<string, number>;
-    }[]): void;
-    removeComponent(entityId: EntityID, def: ComponentDef): this;
-    removeComponents(entityId: EntityID, defs: ComponentDef[]): void;
-    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    /** DEV-only: throw when an *immediate* host structural mutator is called
+     * from inside one of THIS world's system bodies (or an observer / onAdded
+     * hook — they run in the same access spans). One rule for every host
+     * mutator, not just despawn: an immediate structural op mid-schedule can
+     * move or swap rows a running query is walking, and it is invisible to
+     * observers. The archetype-level `_iterDepth` guard only catches mutations
+     * touching the archetype currently being iterated — an op landing elsewhere
+     * would silently skip observers, so the receiver rule ("inside a system,
+     * use ctx.commands") is enforced wholesale here.
+     *
+     * `_updating` scopes the guard to THIS world: the accessCheck slot is
+     * process-global, so without it a system of world A mutating world B (a
+     * supported #785 pattern — B is not mid-iteration) would false-throw. */
+    private _assertHostMutationOutsideSystem;
+    /** Immediately destroy an entity — `ecs.despawn(e); ecs.isAlive(e)` is
+     *  `false` on the next line, matching the immediacy of every other host
+     *  facade mutation. Inside a system the buffered path is
+     *  `ctx.commands.despawn` (applied at the phase flush); calling this from
+     *  a system body throws in DEV, since an immediate destroy mid-iteration
+     *  can invalidate rows the running query is walking. */
+    despawn(id: EntityID): void;
     /** Disable `id` (idempotent). Excluded from default queries until re-enabled. */
     disable(id: EntityID): this;
     /** Re-enable a disabled `id` (idempotent). */
     enable(id: EntityID): this;
-    /** Whether `id` is currently disabled. */
-    isDisabled(id: EntityID): boolean;
-    addSparse(entityId: EntityID, def: SparseComponentDef<Record<string, never>>): this;
-    addSparse<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, values: FieldValues<S>): this;
-    removeSparse(entityId: EntityID, def: SparseComponentDef): this;
-    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
-    getSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S): number;
-    setSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S, value: number): void;
-    /** Register a relation kind. Exclusive (default) stores one target per
-     * source in a backing sparse component; `{ multi: true }` stores a target
-     * set per source. `{ onDeleteTarget: "delete" | "clear" | "orphan" }`
-     * selects what happens to a relation's sources when a target is destroyed
-     * (default `orphan`, #473). See `registerRelation` on `Store` / ADR-0011. */
-    registerRelation(opts?: RelationOptions): RelationDef;
-    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target;
-     * multi adds to the set. No archetype transition. */
-    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): this;
-    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
-     * all of `src`'s targets. No archetype transition. */
-    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): this;
-    /** The single target of `src` under an exclusive relation, or `undefined`. */
-    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
-    /** All targets of `src` under `R`, ascending by id. */
-    targetsOf(src: EntityID, def: RelationDef): EntityID[];
-    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id. */
-    sourcesOf(def: RelationDef, tgt: EntityID): EntityID[];
-    /** Whether `src` holds any pair under `R`. */
-    hasRelation(src: EntityID, def: RelationDef): boolean;
-    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
-     * (#472). Sources in canonical entity-index order; a multi source's targets
-     * ascending by id. Cold path. */
-    pairsOf(def: RelationDef): [EntityID, EntityID][];
-    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds —
-     * the `(*, T)` wildcard (#472). Ordered by relation id then source id. The
-     * single-relation form is `sourcesOf(def, tgt)`. */
-    sourcesOfAny(tgt: EntityID): [RelationDef, EntityID][];
-    /** Reclaim relation reverse-index memory: drop every reverse entry whose
-     * target has been destroyed, returning the total dropped (#491). Under the
-     * default `orphan` policy a destroyed target's reverse entry lingers until
-     * each source re-targets or dies, so orphan-pointing at a churn of
-     * short-lived targets grows the index without bound. A purely cold-path
-     * reclaim — no observable state change (forward links stay dangling per
-     * `orphan`, `stateHash` is unaffected) — call it at scene/snapshot
-     * boundaries. */
-    compactRelations(): number;
-    /** Walk relation `R` up from `src` to its chain root, returning
-     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
-    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
-    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
-     * Exclusive only. */
-    rootOf(src: EntityID, def: RelationDef): EntityID;
-    /** Walk relation `R` down from `root` over the reverse index, returning the
-     * subtree (including `root`) breadth-first — parents before children (the
-     * `cascade` order). Exclusive only. */
-    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
+    /**
+     * Attach a component to an entity, immediately (inside a system, use the
+     * deferred `ctx.commands.add`). Three shapes: a bare def attaches a tag; a
+     * bundle (`Pos({ x: 1 })`) zero-fills omitted fields; the explicit
+     * `(e, def, values)` form demands every field, so a typo'd or missing
+     * field is a compile error.
+     *
+     * @example
+     * ecs.addComponent(e, Frozen);                 // tag
+     * ecs.addComponent(e, Pos({ x: 1 }));          // bundle — y zero-fills
+     * ecs.addComponent(e, Pos, { x: 1, y: 2 });    // complete values
+     */
+    addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): this;
+    addComponent<S extends ComponentSchema>(entityId: EntityID, bundle: Bundle<S>): this;
+    addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
+    /** Batch-attach several components in one archetype transition. Each
+     * entry's `values` is checked against its own def's schema (a misspelled
+     * field is a compile error; tags refuse `values`) — same typing as
+     * `ECS.template` entries. Omitted fields zero-fill. */
+    addComponents<Defs extends readonly ComponentDef[]>(entityId: EntityID, entries: TemplateEntries<Defs>): this;
+    removeComponent(entityId: EntityID, def: ComponentDef): this;
+    removeComponents(entityId: EntityID, defs: ComponentDef[]): this;
     /**
      * Bulk add a component to ALL entities in the given archetype.
      * O(columns) via TypedArray.set() instead of O(N×columns).
@@ -377,31 +254,218 @@ export declare class ECS implements QueryResolver {
      * Takes an `ArchetypeID` (from `ArchetypeView.id`) rather than a concrete
      * `Archetype` — the concrete type is internal (issue #378).
      */
-    batchAddComponent(src: ArchetypeID, def: ComponentDef<Record<string, never>>): void;
-    batchAddComponent<S extends ComponentSchema>(src: ArchetypeID, def: ComponentDef<S>, values: FieldValues<S>): void;
+    batchAddComponent(src: ArchetypeID, def: ComponentDef<Record<string, never>>): this;
+    batchAddComponent<S extends ComponentSchema>(src: ArchetypeID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
     /**
      * Bulk remove a component from ALL entities in the given archetype.
      * O(columns) via TypedArray.set() instead of O(N×columns).
      *
      * Takes an `ArchetypeID` (from `ArchetypeView.id`); see `batchAddComponent`.
      */
-    batchRemoveComponent(src: ArchetypeID, def: ComponentDef): void;
+    batchRemoveComponent(src: ArchetypeID, def: ComponentDef): this;
     getField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S): number;
+    /** Host-side parity with `SystemContext.refRead` (POLISH_AUDIT M7): a
+     * read-only whole-component view for tooling/tests, instead of reading
+     * field-by-field. Same advisory-`readonly` semantics as the ctx variant;
+     * no `_changedTick` bump. Dev-throws on a dead entity, or when the entity
+     * doesn't hold the component (tags included — no fields, nothing to ref).
+     *
+     * **Staleness:** unlike ctx refs (protected by deferred structural changes
+     * until the phase flush), host-side structural mutations apply immediately —
+     * any `addComponent`/`removeComponent`/`despawn` after creating the ref can
+     * row-swap so the old ref silently reads *another entity's* data. The ref is
+     * only valid until the next structural mutation; treat it as an immediate
+     * single-expression read and re-create it after any structural change. */
+    refRead<S extends ComponentSchema>(def: ComponentDef<S>, entityId: EntityID): ReadonlyComponentRef<S>;
+    /** Total sibling of {@link getField} (POLISH_AUDIT #9): `undefined` when the
+     * entity is dead or doesn't hold the component, instead of a dev throw /
+     * prod garbage read. The safe way to probe-and-read in one call:
+     * `ecs.tryGetField(e, Health, "current") ?? 0`. */
+    tryGetField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S): number | undefined;
     setField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): void;
     /** Read-modify-write one field: `updateField(e, Gold, "value", v => v - cost)`
      * is the one-line form of the `getField` → compute → `setField` round trip.
      * Returns the written value. Same access-check and observer semantics as the
      * two calls it composes. */
     updateField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, fn: (current: number) => number): number;
-    emit(key: SignalKey): void;
-    emit<S extends EventSchema>(key: EventKey<S>, values: S): void;
-    read<S extends EventSchema>(key: EventKey<S>): EventReader<S>;
+    /**
+     * Get the live, cached query matching entities that have **all** of
+     * `defs`. Queries are deduplicated by mask — calling this twice with the
+     * same terms returns the same instance — so build once at setup and reuse;
+     * the view stays live as archetypes appear. Refine with `.and()` /
+     * `.without()` / `.anyOf()`; iterate with `eachChunk` (mutating hot path),
+     * `forEach` (per-archetype), or `forEachEntity` (per-entity).
+     *
+     * @example
+     * const movers = ecs.query(Pos, Vel);
+     * movers.eachChunk((cols, count) => {
+     *   const { x, y } = cols.mut(Pos);
+     *   const { vx, vy } = cols.read(Vel);
+     *   for (let i = 0; i < count; i++) { x[i] += vx[i]; y[i] += vy[i]; }
+     * });
+     */
     query<T extends ComponentDef[]>(...defs: T): Query<T>;
+    _nextQueryId(): number;
+    /** QueryResolver implementation — creates or retrieves a cached Query. */
+    _resolveQuery(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, defs: readonly ComponentDef[]): Query<any>;
+    /**
+     * Register a system and get its scheduling handle. The config form is the
+     * production shape: it declares the access surface (`reads` / `writes` are
+     * mandatory; `spawns` / `despawns` / resource and sparse/relation terms
+     * optional), which is enforced at runtime in dev *and* narrows `ctx` at
+     * the type level so undeclared access fails to compile. Registration does
+     * not schedule — pass the returned descriptor to
+     * `ecs.addSystems(SCHEDULE.UPDATE, ...)`.
+     *
+     * @example
+     * // Full config — declared access, dev-checked and compile-checked
+     * const move = ecs.registerSystem({
+     *   reads: [Vel],
+     *   writes: [Pos],
+     *   fn(ctx, dt) {
+     *     movers.eachChunk((cols, count) => { ... });
+     *   },
+     * });
+     * ecs.addSystems(SCHEDULE.UPDATE, move);
+     *
+     * @example
+     * // Bare function (no declared access — any component touch throws in dev)
+     * ecs.registerSystem((ctx, dt) => { ... });
+     * // Function + query builder (query resolved at registration time)
+     * ecs.registerSystem((q, ctx, dt) => { q.forEach((arch) => { ... }); }, (qb) => qb.with(Pos, Vel));
+     */
+    registerSystem(fn: SystemFn): SystemDescriptor;
+    registerSystem<Defs extends readonly ComponentDef[]>(fn: (q: Query<Defs>, ctx: SystemContext, dt: number) => void, queryFn: (qb: QueryBuilder) => Query<Defs>): SystemDescriptor;
+    /** `exclusive: true` grants full world access at runtime (§system.ts), so
+     * the context stays fully permissive at the type layer too. Declared BEFORE
+     * the typed-config overload so exclusive configs never get narrowed. */
+    registerSystem(config: SystemConfig & {
+        readonly exclusive: true;
+    }): SystemDescriptor;
+    /** Config form (§typestate, system.ts): the declaration lists are inferred
+     * as literal tuples and `fn` / `onAdded` receive
+     * `SystemContext<DeclaredAccess<…>>` — undeclared access fails to compile
+     * with the same taxonomy the runtime `accessCheck` throws with in
+     * `DEV`. A config VALUE typed as plain `SystemConfig` (dynamically
+     * built) still matches: its erased declaration lists compute a permissive
+     * access record. Escape hatch: annotate `fn(ctx: SystemContext, dt)`
+     * explicitly to keep a system permissive at compile time. */
+    registerSystem<R extends DenseAccessDecl, W extends DenseAccessDecl, Sp extends SpawnsAccessDecl = readonly never[], De extends DespawnsAccessDecl = readonly never[], Tr extends TransitionsAccessDecl = readonly never[], SR extends SparseAccessDecl = readonly never[], SW extends SparseAccessDecl = readonly never[], RR extends RelationsAccessDecl = readonly never[], RW extends RelationsAccessDecl = readonly never[], QR extends ResourcesAccessDecl = readonly never[], QW extends ResourcesAccessDecl = readonly never[]>(config: TypedSystemConfig<R, W, Sp, De, Tr, SR, SW, RR, RW, QR, QW>): SystemDescriptor;
+    removeSystem(system: SystemDescriptor): void;
+    get systemCount(): number;
+    /**
+     * Run the startup phases, once, before the first `update()`. Prewarms
+     * every archetype the registered systems/observers can produce, runs each
+     * system's `onAdded` hook, then the `PRE_STARTUP` → `STARTUP` →
+     * `POST_STARTUP` schedule. Events emitted during startup are drained at
+     * its tail — they do not leak into frame 1.
+     *
+     * @example
+     * ecs.addSystems(SCHEDULE.UPDATE, move);
+     * ecs.startup();
+     * ecs.update(1 / 60); // now tick every frame
+     */
+    startup(): void;
+    /** Compute the archetype closure from every registered system's AND
+     * observer's `spawns` + `transitions` and ask the store to plant the
+     * whole set in one `extendColumnStore` call. Observers carry the same
+     * access shape systems do (a synthesized `SystemDescriptor`), so an
+     * observer that spawns/transitions gets its target archetype prewarmed
+     * too rather than first-touching lazily mid-tick (#768). Exposed as
+     * `private` because the only caller is `startup()`; visible to tests via
+     * the `archetype_count` delta on the public ECS facade. */
+    private prewarmArchetypes;
+    /**
+     * Advance the world one frame. Runs the fixed-timestep accumulator loop
+     * (`FIXED_UPDATE`, when any fixed system is registered), then
+     * `PRE_UPDATE` → `UPDATE` → `POST_UPDATE`, flushing deferred structural
+     * commands at each phase boundary. Events emitted this tick are readable
+     * for the rest of the tick and cleared at the tail. `dt` is in seconds.
+     *
+     * @example
+     * let last = performance.now();
+     * function frame(now: number) {
+     *   ecs.update((now - last) / 1000);
+     *   last = now;
+     *   requestAnimationFrame(frame);
+     * }
+     * requestAnimationFrame(frame);
+     */
+    update(dt: number): void;
+    dispose(): void;
+    /** Resolve a consumer-declared SAB region's byte offset by `region_id`, or
+     * 0 when absent. Generic, de-gamed replacement (#623) for the removed
+     * game-named accessors; pair with the consumer's own region module to
+     * materialise a typed view. Delegates to `Store.regionOffset`. */
+    regionOffset(regionId: number): number;
+    /** A handle (`{ buffer, view, offset, bytes }`) to a consumer-declared SAB
+     * region resolved by `region_id`, or `null` when absent. A consumer's
+     * region module builds a TypedArray view over the region's span from this.
+     * Re-fetch after a SAB grow. Delegates to `Store.regionHandle`. (#623) */
+    regionHandle(regionId: number): ColumnStoreRegionHandle | null;
+    /** Look up the field index a component reserves for `fieldName`. The
+     * index is assigned by `registerComponent` in insertion order and is
+     * stable for the lifetime of the ECS. Used by systems that need to
+     * pass `(component_id, field_id)` pairs across the WASM FFI — the Zig
+     * side identifies columns by these numeric IDs. */
+    fieldId<S extends Record<string, TypedArrayTag>>(def: ComponentDef<S>, fieldName: Extract<keyof S, string>): number;
+    /** Resolve an archetype's row index to the `EntityID` at that slot.
+     * A WASM system that drains events from the event ring as
+     * `(archId, row, …)` payloads uses this to convert the (archId, row)
+     * pair into the `EntityID` the `ctx.emit(...)` API expects.
+     * Throws if the (archId, row) pair is out of range. (#250 / Phase 4
+     * PR 4D) */
+    entityIdAtRow(archetypeId: number, row: number): EntityID;
+    /** The single SAB backing every archetype's column views. Exposed for
+     * snapshot/restore, `columnStoreStateHash`-based determinism checks, and
+     * Phase 2+ WASM/worker hand-off paths. Mutation flows through the
+     * usual `addComponent` / `removeComponent` / `flush` APIs; readers
+     * that hold a column view across a grow must consult
+     * `header.view_stamp` to detect a republish (#171 §8.1). */
+    get columnStore(): ColumnStore;
+    /** Count of live archetypes (including the empty one). Surfaces the
+     * Store-side `archetype_count` so Phase C tests can assert the
+     * pre-warmed closure was materialised; equally useful for diagnostics. */
+    get archetypeCount(): number;
+    registerTag(): ComponentDef<Record<string, never>>;
+    /** Register a sparse tag (empty schema) — membership only, no data. */
+    registerSparseTag(): SparseComponentDef<Record<string, never>>;
+    /** Register an archetype template (#462). Resolves the component set +
+     * default field values to a target archetype once (creating it if absent —
+     * fits the prewarm model), so later `spawn` / `spawnMany` calls land
+     * entities directly in that archetype with **zero archetype transitions**.
+     *
+     *   const Bullet = ecs.template([
+     *     { def: Position, values: { x: 0, y: 0 } },
+     *     { def: Velocity, values: { vx: 0, vy: 0 } },
+     *   ]);
+     *
+     * The big win is multi-component entities and bulk spawns; a single-
+     * component spawn is no faster than `spawn` + `addComponent`, which
+     * already bump-allocates a fresh entity into the target archetype. See
+     * ADR-0010. */
+    template<Defs extends readonly ComponentDef[]>(entries: TemplateEntries<Defs>): Template<Defs>;
+    /** Bulk-spawn `count` entities from `template`, optionally applying one
+     * shared `overrides` object to every spawned row (same typed keys as
+     * `spawn`). Field writes are O(columns) (one `TypedArray.fill` per
+     * column), not O(count×columns). Returns the new ids in spawn order. */
+    spawnMany<Defs extends readonly ComponentDef[]>(template: Template<Defs>, count: number, overrides?: TemplateOverrides<Defs>): EntityID[];
+    isAlive(id: EntityID): boolean;
+    get entityCount(): number;
+    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    /** Whether `id` is currently disabled. Toggle via `disable` / `enable`
+     * (immediate, above the band — they carry the in-system dev guard). */
+    isDisabled(id: EntityID): boolean;
+    addSparse(entityId: EntityID, def: SparseComponentDef<Record<string, never>>): this;
+    addSparse<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, values: CompleteFieldValues<S>): this;
+    removeSparse(entityId: EntityID, def: SparseComponentDef): this;
+    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
+    getSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S): number;
+    setSparseField<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, field: string & keyof S, value: number): void;
     _getLastRunTick(): number;
     /** Current ECS write tick — the tick `eachChunk` stamps via `cols.mut` (§eachChunk). */
     _getCurrentTick(): number;
     _getQueryDirtyEpoch(): number;
-    _nextQueryId(): number;
     /** QueryResolver implementation — sparse-membership match path (#469). */
     _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;
     /** QueryResolver implementation — backing sparse id of a relation, for the
@@ -411,27 +475,6 @@ export declare class ECS implements QueryResolver {
     _forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
     /** QueryResolver implementation — depth-ordered hierarchy match path (#581). */
     _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;
-    /** QueryResolver implementation — creates or retrieves a cached Query. */
-    _resolveQuery(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, defs: readonly ComponentDef[]): Query<any>;
-    private _findCached;
-    /**
-     * Register a system.
-     *
-     *   // Bare function (no query, no lifecycle hooks)
-     *   world.registerSystem((ctx, dt) => { ... });
-     *
-     *   // Function + query builder (query resolved at registration time)
-     *   world.registerSystem(
-     *     (q, ctx, dt) => { q.forEach((arch) => { ... }); },
-     *     (qb) => qb.with(Pos, Vel),
-     *   );
-     *
-     *   // Full config — declares reads/writes (dev-checked) + optional lifecycle hooks
-     *   world.registerSystem({ reads: [Pos, Vel], writes: [Pos], fn(ctx, dt) { ... } });
-     */
-    registerSystem(fn: SystemFn): SystemDescriptor;
-    registerSystem<Defs extends readonly ComponentDef[]>(fn: (q: Query<Defs>, ctx: SystemContext, dt: number) => void, queryFn: (qb: QueryBuilder) => Query<Defs>): SystemDescriptor;
-    registerSystem(config: SystemConfig): SystemDescriptor;
     addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): this;
     /**
      * Configure a `SystemSet` (#576) — the shared run condition and/or ordering
@@ -439,8 +482,6 @@ export declare class ECS implements QueryResolver {
      * `addSystems`: see `Schedule.configureSet`. Returns `this` to chain.
      */
     configureSet(set: SystemSet, config: SystemSetConfig): this;
-    removeSystem(system: SystemDescriptor): void;
-    get systemCount(): number;
     /**
      * Register a per-component observer (#517 §1 / ADR-0013). Reactions that were
      * hand-polled every tick — "on `Death` added → spawn corpse", "on `HexPos`
@@ -455,8 +496,8 @@ export declare class ECS implements QueryResolver {
      *   when an entity carrying the component is *disabled* / *enabled* (#577,
      *   ADR-0023), once per net transition, for every component the entity carries
      *   (a disable is a soft remove of the whole mask from default queries). Like
-     *   `onAdd`/`onRemove`, an *immediate* `world.disable()` does not fire — only
-     *   the deferred `ctx.disable()` toggle does. `yieldExisting` seeds enabled
+     *   `onAdd`/`onRemove`, an *immediate* `ecs.disable()` does not fire — only
+     *   the deferred `ctx.commands.disable()` toggle does. `yieldExisting` seeds enabled
      *   members only, so a disabled entity is correctly absent at seed.
      * - **`onSet`** fires at the post-update detection point. Default
      *   `granularity: "archetype"` fires `(arch, ctx)` once per changed
@@ -469,24 +510,13 @@ export declare class ECS implements QueryResolver {
      *
      * Observer callbacks that touch ECS state must declare it via `access`
      * (merged over an all-empty declaration) — undeclared access throws in
-     * `__DEV__`, and those decls drive the firing order. `yieldExisting` replays
+     * `DEV`, and those decls drive the firing order. `yieldExisting` replays
      * `onAdd` over current matches on registration. Register at world-build time
      * (before `startup()`); the returned handle's `dispose()` unregisters.
      */
-    observe<S extends ComponentSchema>(def: ComponentDef<S>, config: StructuralObserverConfig): ObserverHandle;
-    observe<S extends ComponentSchema>(def: ComponentDef<S>, config: EntitySetObserverConfig): ObserverHandle;
-    observe<S extends ComponentSchema>(def: ComponentDef<S>, config: ArchetypeSetObserverConfig): ObserverHandle;
-    startup(): void;
-    /** Compute the archetype closure from every registered system's AND
-     * observer's `spawns` + `transitions` and ask the store to plant the
-     * whole set in one `extendColumnStore` call. Observers carry the same
-     * access shape systems do (a synthesized `SystemDescriptor`), so an
-     * observer that spawns/transitions gets its target archetype prewarmed
-     * too rather than first-touching lazily mid-tick (#768). Exposed as
-     * `private` because the only caller is `startup()`; visible to tests via
-     * the `archetype_count` delta on the public ECS facade. */
-    private prewarmArchetypes;
-    update(dt: number): void;
+    observe(def: ComponentHandle, config: StructuralObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: EntitySetObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: ArchetypeSetObserverConfig): ObserverHandle;
     /**
      * Stamp every SAB-backed archetype's live `length` into its SAB
      * descriptor's `row_count` field. **You usually don't need to call
@@ -501,7 +531,6 @@ export declare class ECS implements QueryResolver {
      */
     publishArchetypeRowCounts(): void;
     flush(): void;
-    dispose(): void;
 }
 /** Phase C of issue #213 — archetype closure from a descriptor set.
  *