@oasys/oecs 0.4.0 → 0.5.1

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

@@ -3,7 +3,7 @@
  *
  * Singleton buffer that captures `(callsite, channel, op, key)` per ECS /
  * action dispatch when `VISUAL_INTEL_TRACE=1` is set in the environment.
- * Compile-time gated by `__DEV__`, so production builds dead-code-eliminate
+ * Compile-time gated by `DEV`, so production builds dead-code-eliminate
  * every record() call. Output is a deterministic JSON snapshot the
  * `visual-intel` service can ingest as a third channel of evidence
  * alongside the existing static + symbol-propagation scans.
@@ -30,9 +30,9 @@
  *
  * Activation. `record()` is *unconditional* — it records on every call. The
  * `isActive()` env-var gate is applied by the *callers* (`ecs.ts` /
- * `query.ts`, all `if (__DEV__ && dispatchTrace.isActive())`), not inside
+ * `query.ts`, all `if (DEV && dispatchTrace.isActive())`), not inside
  * `record()`. This keeps the gate in one place — the dispatch hot path —
- * where `__DEV__ === false` dead-code-eliminates the whole branch in prod.
+ * where `DEV === false` dead-code-eliminates the whole branch in prod.
  */
 export type DispatchChannel = "ecs-events" | "actions" | "resources";
 export type EcsEventOp = "emit" | "read";

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

@@ -0,0 +1,580 @@
+import { Template, TemplateOverrides } from './store.cjs';
+import { FrameTraceSink } from './frame_trace.cjs';
+import { ObserverHandle, EntitySetObserverConfig, ArchetypeSetObserverConfig, StructuralObserverConfig } from './observer.cjs';
+import { ColumnStore, ColumnStoreRegionHandle, StoreRegionSpec } from '../store/index.cjs';
+import { ECSRelations, ECSEvents, ECSResources, ECSSnapshots } from './facades.cjs';
+import { SCHEDULE, SystemEntry, SystemSet, SystemSetConfig } from './schedule.cjs';
+import { Archetype, ArchetypeID } from './archetype.cjs';
+import { SystemContext, Query, QueryBuilder, QueryCache, QueryResolver } from './query.cjs';
+import { EntityID } from './entity.cjs';
+import { ReadonlyComponentRef } from './ref.cjs';
+import { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, CompleteFieldValues, Bundle, BundleOrDef, StrictBundles, DefsOf } from './component.cjs';
+import { SparseComponentDef, SparseComponentID } from './sparse_store.cjs';
+import { RelationDef } from './relation.cjs';
+import { SystemFn, SystemConfig, SystemDescriptor, TypedSystemConfig, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.cjs';
+import { BitSet, TypedArrayTag } from '../../type_primitives/index.cjs';
+import { StoreLayoutListener } from './store_layout_listener.cjs';
+import { ComputeBackend } from './compute_backend.cjs';
+import { ResolvedECSMemory, ECSMemoryOptions } from './ecs_memory.cjs';
+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:
+     * `{ budget: { entities } }` (derive everything), `{ maxBytes }`
+     * (explicit cap), `{ wasm: { memory } | { maximumPages } }` (the SAB
+     * IS a WebAssembly.Memory — zero-copy with a WASM `ComputeBackend`), or
+     * `{ allocator }` (expert escape hatch, in-place-typed per ADR-0008).
+     * Omitted ⇒ growable backing with a 256 MiB cap and 1024-row columns.
+     * The resolved plan is exposed as `ECS.memoryPlan`. */
+    memory?: ECSMemoryOptions;
+    /** Consumer-declared SAB regions (#623), forwarded to `Store`. Each
+     * `StoreRegionSpec` carries an opaque `region_id`, a precomputed byte size,
+     * and an `init` closure; the engine lays them out generically and exposes
+     * them via `regionHandle(id)` / `regionOffset(id)`. A game (e.g.
+     * `@internal/sim`'s region specs) supplies these — the engine ships no
+     * game regions of its own. Replaces the eight game-named region options
+     * (`terrain_map_radius`, `spatial_grid_*`, `army_*`, `flow_field_*`,
+     * `actionRingCapacitySlots`) the ECS used to carry. (ADR-0018.) */
+    regions?: readonly StoreRegionSpec[];
+    /** Byte size of the opt-in sim-bindings region (#625), forwarded to `Store`.
+     * A consumer that attaches a WASM `ComputeBackend` passes its own size — for
+     * this game, `@internal/sim`'s `SIM_BINDINGS_BYTES` (computed from the binding
+     * manifest) — so the host can publish the `(component_id, field_id)` IDs the
+     * accelerated systems read. Omitted / 0 ⇒ no region: a pure-TS world pays
+     * nothing for the WASM seam. The size is a runtime input, not an engine ABI
+     * constant, since #625 de-welded it from the generated ABI. */
+    bindingsRegionBytes?: number;
+    /** Opt into the **determinism surface** (#626 / ADR-0020), forwarded to
+     * `Store`. Default `false`. When `false`, the canonical-ordering methods
+     * (`stateHash`, `snapshotSparse`, `restoreSparse`) throw
+     * `DETERMINISM_DISABLED`; when `true`, today's replay/hash behavior is
+     * reproduced bit-for-bit. Determinism is the implementer's choice — our
+     * server match opts in (replay verification), the client stays off (it rolls
+     * back via diffs, not re-sim). The flag gates ONLY that surface: memory-safety
+     * invariants (the in-place SAB allocator, ADR-0008) and the `enabled_count`
+     * partition are always-on regardless. */
+    deterministic?: boolean;
+}
+export declare class ECS implements QueryResolver {
+    private readonly store;
+    private readonly schedule;
+    private readonly ctx;
+    /** 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 scratchMask;
+    private _nextQueryIdCounter;
+    /** @internal Query-composition caches (QueryResolver seam) — not public API. */
+    readonly _caches: QueryCache;
+    private readonly _layoutSubscribers;
+    private _backend;
+    private readonly _memory;
+    /** What `ECSOptions.memory` resolved to (#682): backing allocator kind,
+     * column capacity, entity-index reservation, byte cap, and a
+     * human-readable derivation trace. Diagnostics surface — log it when
+     * sizing questions come up instead of reverse-engineering the SAB. */
+    get memoryPlan(): ResolvedECSMemory;
+    /** The backing `WebAssembly.Memory` when `memory.wasm` was used (both
+     * bring-your-own and engine-constructed), else `null`. A consumer hands
+     * this to its WASM `ComputeBackend` so the sim and the live columns
+     * share the same bytes. */
+    get wasmMemory(): WebAssembly.Memory | null;
+    constructor(options?: ECSOptions);
+    /** 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
+     * of a null-guard per region. Same staleness rule as `regionHandle`:
+     * re-fetch after a SAB grow. */
+    regionHandles(...regionIds: number[]): ColumnStoreRegionHandle[];
+    /** Subscribe to SAB-layout publications. `listener.setLayout(0)` is
+     * called immediately to seed the initial layout, then again after
+     * every SAB grow / extend (the `view_stamp` republish protocol).
+     * Returns an unsubscribe function.
+     *
+     * The engine has no concept of what subscribes — it publishes SAB layouts
+     * and walks away. A consumer subscribes whatever wrapper it owns (a compute
+     * backend, a Worker proxy, a debug recorder) and drives it from its own
+     * code. A `ComputeBackend` is subscribed automatically by `attachBackend`,
+     * so most consumers call that rather than this directly. */
+    onStoreLayoutPublished(listener: StoreLayoutListener): () => void;
+    /** Attach an opt-in compute backend (#622). Default is none: a bare `ECS`
+     * runs pure-TS systems and the schedule's dispatch is byte-for-byte the
+     * no-backend path. Once attached, a scheduled system carrying a
+     * `backendHandle` (its `SystemConfig`) is executed via `backend.run(handle)`
+     * instead of its `fn` closure; systems without a handle are unaffected.
+     *
+     * The backend is also subscribed as a SAB-layout listener (seeded now, then
+     * republished on every grow), folding in the `onStoreLayoutPublished` seam.
+     * Returns a detach function that unsubscribes the layout listener and reverts
+     * 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
+     * `setLayout` / `run` — it carries no game vocabulary. */
+    attachBackend(backend: ComputeBackend): () => void;
+    get fixedTimestep(): number;
+    set fixedTimestep(value: number);
+    get fixedAlpha(): number;
+    /** 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
+     * can reconstruct exactly what travelled through the ECS each frame. The sink
+     * 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
+     * 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;
+    /**
+     * 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.
+     *
+     * The handle is *callable*: `Pos({ x: 1 })` mints a `Bundle` for the
+     * attach surfaces (`spawnBundle`, `ctx.commands.spawn`, `addComponent`).
+     *
+     * @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;
+    }>;
+    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;
+    }>;
+    /**
+     * 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.
+     *
+     * @example
+     * const e = ecs.spawn();
+     * ecs.addComponent(e, Pos, { x: 0, y: 0 });
+     *
+     * 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`, and the same callable-bundle
+     * grammar as `addComponents` / `template`. `ecs.spawnBundle(Pos({x,y}),
+     * Vel({vx:1}), IsEnemy)` collapses the attach shapes into one; each item is
+     * checked against its own def's schema (`StrictBundles`). Bundles are applied
+     * immediately; a single combined-archetype insertion (one transition instead
+     * of one-per-component) is a later optimization — for now this mirrors the
+     * per-component `addComponent` path (unlike `addComponents`, which batches).
+     *
+     * Immediate — inside a system use the deferred `ctx.commands.spawn(...)`
+     * (calling this from a system body throws in DEV). Note the redirect trades
+     * timing: `commands.spawn` returns the id now but defers the attaches to the
+     * phase flush, so the entity sits in its empty/partial archetype until then —
+     * unlike `spawnBundle`'s immediate, fully-populated archetype.
+     */
+    spawnBundle<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): EntityID;
+    /** 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.
+     * Immediate — inside a system use `ctx.commands.spawn` per entity (calling
+     * this from a system body throws in DEV). */
+    spawnMany<Defs extends readonly ComponentDef[]>(template: Template<Defs>, count: number, overrides?: TemplateOverrides<Defs>): EntityID[];
+    /** 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
+     * structural mutator — despawn, add/remove(Components), batchAdd/Remove,
+     * disable/enable, AND the spawn family (spawn/spawnBundle/spawnMany): an
+     * immediate structural op mid-schedule can move or swap rows a running query
+     * is walking — or, for a spawn-append into that archetype, trip a column
+     * realloc under it — and it is invisible to observers. The archetype-level
+     * `_iterDepth` guard only catches mutations touching the archetype currently
+     * being iterated (and the append paths skip even that), so an op landing
+     * elsewhere would silently skip observers; 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(entityId: EntityID): this;
+    /** Disable `entityId` (idempotent). Excluded from default queries until re-enabled. */
+    disable(entityId: EntityID): this;
+    /** Re-enable a disabled `entityId` (idempotent). */
+    enable(entityId: EntityID): this;
+    /**
+     * 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. Takes the
+     * same callable-bundle varargs as `spawnBundle` — `world.addComponents(e,
+     * Pos({ x, y }), Vel({ vx }), Frozen)` — each item checked against its own
+     * def's schema (a misspelled or cross-component field is a compile error;
+     * tags refuse values). Omitted fields zero-fill. */
+    addComponents<Items extends readonly BundleOrDef[]>(entityId: EntityID, ...items: StrictBundles<Items>): this;
+    removeComponent(entityId: EntityID, def: ComponentDef): this;
+    /** Detach several components in one archetype transition — the varargs
+     * mirror of `addComponents` (bare defs; removing needs no values). */
+    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).
+     *
+     * 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>>): 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): 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;
+    /**
+     * 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): this;
+    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;
+    /** 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(Position({ x: 0, y: 0 }), Velocity({ vx: 0, vy: 0 }));
+     *
+     * Takes the same callable-bundle varargs as `spawnBundle` / `addComponents`
+     * (each item schema-checked against its own def); the resulting
+     * `Template<[Position, Velocity]>` keeps the typed key set that `spawn`'s
+     * `overrides` map over. Not a pass-through — it normalizes bundles to the
+     * store's entry shape, so it lives here with the other real logic, not in the
+     * delegation band. 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<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): Template<DefsOf<Items>>;
+    /** 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>>;
+    isAlive(entityId: EntityID): boolean;
+    get entityCount(): number;
+    hasComponent(entityId: EntityID, def: ComponentDef): boolean;
+    /** Whether `entityId` is currently disabled. Toggle via `disable` / `enable`
+     * (immediate, above the band — they carry the in-system dev guard). */
+    isDisabled(entityId: 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;
+    /** 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
+     * `(R, *)` wildcard term (`Query.withRelation`, #579). */
+    _relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** QueryResolver implementation — `(*, T)` wildcard match path (#579). */
+    _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;
+    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): this;
+    /**
+     * Configure a `SystemSet` (#576) — the shared run condition and/or ordering
+     * every member inherits. Additive and order-independent with respect to
+     * `addSystems`: see `Schedule.configureSet`. Returns `this` to chain.
+     */
+    configureSet(set: SystemSet, config: SystemSetConfig): this;
+    /**
+     * Register a per-component observer (#517 §1 / ADR-0013). Reactions that were
+     * hand-polled every tick — "on `Death` added → spawn corpse", "on `HexPos`
+     * set → mark the spatial index" — become declarative.
+     *
+     * - **`onAdd` / `onRemove`** `(eid, ctx)` fire at the structural-flush
+     *   boundary, after the batch commits, in canonical order (access-topological
+     *   across observers, entity-id order within), looping to a fixed point so
+     *   cascades settle. Determinism: a `stateHash` replay reproduces regardless
+     *   of the order ops were queued.
+     * - **`onDisable` / `onEnable`** `(eid, ctx)` fire at the same flush boundary
+     *   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* `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
+     *   archetype-column (the consumer iterates `arch.entityCount` rows) — free,
+     *   reusing the change tick. `granularity: "entity"` fires `(eid, ctx)` once
+     *   per changed entity, draining the opt-in per-row dirty list (registering it
+     *   enables dirty tracking for the component; the producer records via
+     *   `ctx.setField` automatically, or `ctx.markChanged` in a `getColumn`
+     *   hot loop).
+     *
+     * 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
+     * `onAdd` over current matches on registration. Register at world-build time
+     * (before `startup()`); the returned handle's `dispose()` unregisters.
+     */
+    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
+     * this directly** — `update()` publishes at tick start and
+     * `SystemContext.flush()` publishes at every phase boundary, so any
+     * WASM scan running inside the schedule sees fresh counts for free.
+     * This is an escape hatch for code that mutates archetype state
+     * outside the system framework and wants to force a republish without
+     * going through `flush()`. No in-repo callers today.
+     *
+     * Cheap: walks the descriptor region once, does no column I/O.
+     */
+    publishArchetypeRowCounts(): void;
+    flush(): void;
+}
+/** Phase C of issue #213 — archetype closure from a descriptor set.
+ *
+ * Each descriptor is a system or an observer's synthesized `SystemDescriptor`
+ * (#768) — both carry `spawns` + `transitions`. Seeds the worklist with every
+ * descriptor's `spawns`; iteratively applies every descriptor's `transitions`
+ * to every discovered mask whose components cover the transition's `whenHas`.
+ * Returns the union of seeds + reachable targets, deduplicated by hash-bucketed
+ * mask equality.
+ *
+ * Termination: every transition either monotonically grows the mask (add
+ * outpacing remove), monotonically shrinks it, or returns a mask the
+ * `seen` map already holds. Because the universe of masks is bounded by
+ * `2^|components|` (and in practice the in-tree spawn/transition set is
+ * tiny — ~20 masks at most), the worklist is finite and we exit when it
+ * empties.
+ *
+ * Liberal `whenHas` per design doc §6.6 — over-approximation is fine; an
+ * unreachable transition target costs one descriptor row at the SAB tail,
+ * not column bytes. Empty `spawns` + `transitions` short-circuit to zero.
+ */
+declare function computeArchetypeClosure(descriptors: Iterable<SystemDescriptor>): BitSet[];
+/** @internal — test seam for the closure walk. Exposed so the prewarm
+ * tests can exercise the BFS without standing up a full Store. */
+export declare const _ecsInternals: {
+    computeArchetypeClosure: typeof computeArchetypeClosure;
+};
+export {};
+//# sourceMappingURL=ecs.d.ts.map